API Documentation
Support

Getting started with conversion tracking

This guide walks you through adding the conversion tracking SDK to your website or web app. By the end, you will have the script installed, installation verified, and your first conversion event firing.

Step 1: Generate your conversion tracking key

Your conversion tracking key is generated in Rebrandly. It cannot be created via the API, and other Rebrandly API keys cannot be used for tracking.

In Rebrandly, open Settings, navigate to Conversion tracking, then click Step 1 > Create API key.

📘

Your conversion tracking key is intentionally public

This key will be visible in your site's source code as part of the script tag. That is expected and safe. It is not the same as a Rebrandly API key, which must always be kept private.

📘

Create one key per site

Create one conversion tracking key for each website or app you instrument. This keeps conversion data clean and makes access management easier if you need to rotate or revoke keys later.

For a full UI walkthrough, see How do I set up conversion tracking? in the Help Center.

Step 2: Add the script to your site

Add the following tag to the <head> element of your website, replacing YOUR_KEY with the key you generated in step 1. The script will also be auto-generated for you after you create the key.

<script src="https://cdn.rebrandly.com/analytics/sdk/v1/rbly.min.js" data-api-key="YOUR_KEY"></script>

Step 3: Verify installation

When the SDK initializes, it writes one of the following messages to the browser console:

  • [Rebrandly SDK] Initialized with click ID: {id} — an rbly_click_id was found and stored
  • [Rebrandly SDK] Initialized (no click ID found) — the page was not loaded via a branded link

To confirm the SDK is sending events, call rbly.convert() and then check the Network tab in your browser dev tools for a request to {apiBase}/v1/track/conversion.

Step 4: Fire your first event

rbly.convert() is the method for recording conversion events. For monetary conversions, pass value and currency:

rbly.convert('purchase', 19.99, 'USD', { orderId: 'ORDER-123' });

For non-monetary conversions, pass only a label:

rbly.convert('signup');

The custom events page covers rbly.convert() in depth, including all supported parameters and the response schema.

🚧

No sandbox or test mode

There is no sandbox or test mode. Conversion tracking operates at the workspace level and cannot currently be scoped to a specific link, so there is no way to isolate test events from production data. Give test events clearly identifiable names — for example test_purchase or dev_signup — so they can be identified and excluded from reports manually.

🚧

localStorage restrictions

If localStorage is blocked — as it can be in Safari with ITP enabled, Firefox in strict tracking protection mode, or any browser in private browsing mode — the SDK cannot persist the rbly_click_id. In that case, rbly.convert() returns { success: false, error: 'no_click_id' } and the conversion is not recorded. There is no fallback mechanism.

Next steps

Updated about 19 hours ago