How to convert events from customer side

This guide explains how to integrate BreadCrumbs tracking into your website or application to convert events and trigger rewards for successful conversions.

Understanding the tracking flow

BreadCrumbs uses a postback tracking system based on blockchain technology to ensure trustlessness and transparency. Here’s how it works:

Referral Click: A user clicks on a campaign referral/affiliate link
Crumb Creation: BreadCrumbs creates a tracking event (“crumb”) with a unique ID
Redirect: The user is redirected to your website with the crumbId in the URL
Conversion: When the user completes the desired action on your site, you send the crumbId back by sending a “pick” request from your server to confirm the conversion
Reward: BreadCrumbs processes the conversion and distributes rewards on-chain

For Click Through conversion types, the process is fully automatic. No integration is required as conversions are registered immediately upon clicking the referral link.

Integration architecture

For security reasons, BreadCrumbs tracking service must be integrated using a server side approach:

Client side: Only used to retrieve the crumbId from URL parameters
Server side: Required to securely send conversion requests to BreadCrumbs Tracker API

Your BreadCrumbs API credentials must never be exposed client side. All conversion requests to BreadCrumbs API must be made from your server.

Step-by-step integration guide

Get your API credentials

You’ll need two credentials to authenticate your API requests:

Client ID: Your unique identifier
Client Secret: Your secret key for authorization

These can be found in BreadCrumbs App > Builders > Campaigns > [Your Campaign] > Security page of your campaign dashboard.

Get the conversion type

The conversion type is the one that is set in the campaign dashboard. Please go to BreadCrumbs App > Builders > Campaigns > [Your Campaign] > Integration page to check it.

It can be one of the following:

UrlVisit
DomainVisit
TimeOnPage
LeadGeneration
WalletConnection
ChannelSubscription
SignUp
Membership
AppInstallation
FreeTrialRegistration
FirstDeposit
TokenPurchase
Transaction
Sale
Referral
CustomAction

Client Side: Retrieve the Crumb ID

When users click on affiliate links and are redirected to your site, they’ll arrive with a crumbId parameter in the URL:

https://your-website.com/your-page?crumbId=1234567890

You need to extract this parameter (crumbId) on the client side and send it to your own server.

React/Next.js Example:

import { useSearchParams } from "next/navigation";
 
export default function Component() {
  const searchParams = useSearchParams();
  const crumbId = searchParams.get('crumbId');
  
  // Store or use the crumbId
  useEffect(() => {
    if (crumbId) {
      // Option 1: Store in local storage
      localStorage.setItem('breadcrumbs_crumb_id', crumbId);
      
      // Option 2: Send to your server immediately
      fetch('/api/store-crumb-id', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ crumbId })
      });
    }
  }, [crumbId]);
  
  // Rest of your component
}

Server Side: Send Conversion Request

When a user completes the desired action (signs up, makes a purchase, etc.), your server must send a request to the BreadCrumbs API to confirm the conversion.

Endpoint:

POST https://breadcrumbs.tech/api/tracker/v1/pick

Headers:

Content-Type: application/json
X-Client-Id: YOUR_CLIENT_ID
X-Client-Secret: YOUR_CLIENT_SECRET

Where:

YOUR_CLIENT_ID: Your campaign’s Client ID (check step 1)
YOUR_CLIENT_SECRET: Your authorized Client Secret (check step 1)

Request Body:

{
  "crumbId": "CRUMB_ID",
  "conversionType": "CONVERSION_TYPE"
}

Where:

CRUMB_ID: The crumbId extracted from the URL parameters on the client side
CONVERSION_TYPE: The conversion type configured for your campaign (check step 2)

const BREADCRUMBS_CLIENT_ID = process.env.BREADCRUMBS_CLIENT_ID || '';
const BREADCRUMBS_CLIENT_SECRET = process.env.BREADCRUMBS_CLIENT_SECRET || '';
const BREADCRUMBS_TRACKER_API_URL = 'https://breadcrumbs.tech/api/tracker/v1';
 
async function convertEvent(crumbId, conversionType) {
  const url = `${BREADCRUMBS_TRACKER_API_URL}/pick`;
  
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Client-Id': BREADCRUMBS_CLIENT_ID,
        'X-Client-Secret': BREADCRUMBS_CLIENT_SECRET,
      },
      body: JSON.stringify({ 
        crumbId,
        conversionType
      }),
    });
    
    return await response.json();
  } catch (error) {
    console.error('Error converting event:', error);
    throw error;
  }
}

import os
import requests
 
BREADCRUMBS_CLIENT_ID = os.getenv('BREADCRUMBS_CLIENT_ID')
BREADCRUMBS_CLIENT_SECRET = os.getenv('BREADCRUMBS_CLIENT_SECRET')
BREADCRUMBS_TRACKER_API_URL = 'https://breadcrumbs.tech/api/tracker/v1'
 
def convert_event(crumb_id, conversion_type):
  url = f'{BREADCRUMBS_TRACKER_API_URL}/pick'
  
  try:
    response = requests.post(
      url, 
      headers={
        'Content-Type': 'application/json',
        'X-Client-Id': BREADCRUMBS_CLIENT_ID,
        'X-Client-Secret': BREADCRUMBS_CLIENT_SECRET,
      },
      json={
        'crumbId': crumb_id,
        'conversionType': conversion_type
      }
    )
    
    return response.json()
  except Exception as e:
    print(f"Error converting event: {e}")
    raise

import com.fasterxml.jackson.databind.ObjectMapper;
import okhttp3.*;
import org.json.JSONObject;
 
public class BreadCrumbsService {
  private static final String BREADCRUMBS_CLIENT_ID = System.getenv("BREADCRUMBS_CLIENT_ID");
  private static final String BREADCRUMBS_CLIENT_SECRET = System.getenv("BREADCRUMBS_CLIENT_SECRET");
  private static final String BREADCRUMBS_TRACKER_API_URL = "https://breadcrumbs.tech/api/tracker/v1";
  
  public static JSONObject convertEvent(String crumbId, String conversionType) throws IOException {
    OkHttpClient client = new OkHttpClient();
    String url = BREADCRUMBS_TRACKER_API_URL + "/pick";
    
    // Create JSON request body
    JSONObject requestBody = new JSONObject();
    requestBody.put("crumbId", crumbId);
    requestBody.put("conversionType", conversionType);
    
    Request request = new Request.Builder()
      .url(url)
      .addHeader("Content-Type", "application/json")
      .addHeader("X-Client-Id", BREADCRUMBS_CLIENT_ID)
      .addHeader("X-Client-Secret", BREADCRUMBS_CLIENT_SECRET)
      .post(RequestBody.create(requestBody.toString(), MediaType.parse("application/json")))
      .build();
    
    Response response = client.newCall(request).execute();
    String responseBody = response.body().string();
    
    return new JSONObject(responseBody);
  }
}

using System;
using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json;
using System.Threading.Tasks;
 
public class BreadCrumbsService
{
  private static readonly string BREADCRUMBS_CLIENT_ID = Environment.GetEnvironmentVariable("BREADCRUMBS_CLIENT_ID");
  private static readonly string BREADCRUMBS_CLIENT_SECRET = Environment.GetEnvironmentVariable("BREADCRUMBS_CLIENT_SECRET");
  private static readonly string BREADCRUMBS_TRACKER_API_URL = "https://breadcrumbs.tech/api/tracker/v1";
  
  public static async Task<JsonDocument> ConvertEventAsync(string crumbId, string conversionType)
  {
    using var client = new HttpClient();
    var url = $"{BREADCRUMBS_TRACKER_API_URL}/pick";
    
    var requestBody = new
    {
      crumbId = crumbId,
      conversionType = conversionType
    };
    
    var request = new HttpRequestMessage(HttpMethod.Post, url);
    request.Headers.Add("X-Client-Id", BREADCRUMBS_CLIENT_ID);
    request.Headers.Add("X-Client-Secret", BREADCRUMBS_CLIENT_SECRET);
    request.Content = JsonContent.Create(requestBody);
    
    var response = await client.SendAsync(request);
    var responseStream = await response.Content.ReadAsStreamAsync();
    
    return await JsonDocument.ParseAsync(responseStream);
  }
}

Handle the response

The API will respond with a status 200 indicating whether the conversion was successful:

{
  "message": "Crumb picking process started. Check the crumb status at any time using the link.",
  "link": "https://breadcrumbs.tech/api/tracker/v1/crumbs/1234567890"
}

Refer to the BreadCrumbs Tracker API Docs for more details on the response structure and possible errors.

Make sure to handle these errors gracefully in your implementation.

Live Demo

For a complete working example, check out our BreadCrumbs Customer Demo and its GitHub repository.

The demo includes:

Client side code for extracting the crumbId (app/page.tsx)
Server side code for sending conversion requests (app/api/convert/route.ts)

Best Practices

Store the crumbId securely - Use cookies, local storage, or server side sessions to remember the crumbId across pages. Server side is always more secure.
Keep API credentials secure - Never expose your Client ID and Client Secret in client side code. Always make API requests from your server.
Use environment variables - Store your API credentials in environment variables, not hardcoded in your application.
Implement proper error handling - Handle API errors gracefully and provide feedback to users when appropriate.
Test thoroughly - Test your integration in both development and production environments.
Monitor conversions - Regularly check your campaign analytics to ensure conversions are being tracked correctly.

Troubleshooting

Common Issues

Missing crumbId in URL: Make sure users are arriving via proper referral links.
Authentication errors: Verify your Client ID and Client Secret are correct.
No conversions showing: Check that the conversion type in your request matches your campaign configuration.
CORS errors: If attempting direct client side API calls (not recommended), you’ll encounter CORS issues. Always use server side integration.

Getting Help

If you’re experiencing issues with your integration, you can:

Reach out directly to our founder on X

API Reference

For detailed information about all available API endpoints and parameters, please refer to our BreadCrumbs Tracker API Docs.

Guide: How to configure a campaign Partnership Acquisition Roadmap