DocsDevelopersGuide: How to convert events from customer side

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:

  1. Referral Click: A user clicks on a campaign referral/affiliate link
  2. Crumb Creation: BreadCrumbs creates a tracking event (“crumb”) with a unique ID
  3. Redirect: The user is redirected to your website with the crumbId in the URL
  4. 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
  5. 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:

  1. Client side: Only used to retrieve the crumbId from URL parameters
  2. 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;
  }
}

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:

Best Practices

  1. Store the crumbId securely - Use cookies, local storage, or server side sessions to remember the crumbId across pages. Server side is always more secure.

  2. Keep API credentials secure - Never expose your Client ID and Client Secret in client side code. Always make API requests from your server.

  3. Use environment variables - Store your API credentials in environment variables, not hardcoded in your application.

  4. Implement proper error handling - Handle API errors gracefully and provide feedback to users when appropriate.

  5. Test thoroughly - Test your integration in both development and production environments.

  6. Monitor conversions - Regularly check your campaign analytics to ensure conversions are being tracked correctly.

Troubleshooting

Common Issues

  1. Missing crumbId in URL: Make sure users are arriving via proper referral links.

  2. Authentication errors: Verify your Client ID and Client Secret are correct.

  3. No conversions showing: Check that the conversion type in your request matches your campaign configuration.

  4. 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:

API Reference

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