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
: ThecrumbId
extracted from the URL parameters on the client sideCONVERSION_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:
- 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.