Attribution with Addressable Pixel (Recommended)

Some customers use both the Addressable Pixel (for on-site tracking) and the Events API (for off-chain ingestion, backend events, or events from 3rd-party apps). In that setup, you need to include a specific user identifier in your Events API payload so Addressable can correctly attribute those server-side events to the same user sessions the Pixel observed.

If you're using both the Pixel and API, it is generally always recommended to follow this guide.

When is this needed

Use this guide if:

• You already have the Addressable Pixel installed on your website (via GTM or JS).

• You also send events through the Events API.

• You are running campaigns with Addressable.

• You need like Campaign Attribution for the Event sent by the Events API.

Overview of Needs

The Addressable Pixel creates a browser-side identifier stored in local storage at:

• Key: ___adrsbl_nonce

To connect Events API events to Pixel-tracked sessions, you will:

1. Read ___adrsbl_nonce from local storage on the frontend.

2. Store that value alongside your internal user identifier (user id, wallet address, etc.).

3. Send it with every Events API call as an event property [see api docs]:

   • properties: [{ "name": "user_id", "value": "<___adrsbl_nonce value>" }]

That “join key” allows Addressable to attribute server-side events to users who visited your website from campaigns (post-view and post-click where supported).

Getting Started

— Step 1 —

Read ___adrsbl_nonce on page view (frontend)

Add a small snippet that runs on page load (or at least before you plan to associate the user with your backend identity):

const adrsblNonce = window.localStorage.getItem("___adrsbl_nonce");
// Store this somewhere safe for a given user in your backend flow (see Step 2)

✅ Tip: If adrsblNonce is null, confirm the Pixel is loading and firing on that page.

— Step 2 —

Store the nonce alongside your user record (backend)

When you know who the user is (login, signup, wallet connect, etc.), persist:

• your internal identifier (internal id / wallet)

• the latest adrsblNonce you saw for them

A common pattern is to send the nonce to your backend on logged-in pageview:

await fetch("/api/identify-addressable", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    userId: "<your-internal-user-id-or-wallet>",
    addressableUserId: adrsblNonce
  })
});

— Step 3 —

Include it in every Events API call (properties → user_id)

The Events API supports an optional properties field that is a list of JSON objects. Each property uses name and value. (addressable.gitbook.io)

Add this property to your Events API data payload:

"properties": [
  { "name": "user_id", "value": "<addressableUserId from ___adrsbl_nonce>" }
]

That’s it — once the same user_id is present on Events API events, Addressable can connect them back to Pixel sessions for campaign attribution. (addressable.gitbook.io)

Example Payload

Below is an example data JSON (before base64 encoding) showing the properties format:

{
  "tid": "<your pixel id>",
  "event_name": "signup",
  "page_url": "https://example.com/signup",
  "referrer": "https://example.com/",
  "timestamp": 1730538892,
  "timezone_name": "America/New_York",
  "timezone_offset": 240,
  "properties": [
    { "name": "user_id", "value": "c96043..." },
    { "name": "another_example", "value": "yes_it_is" }
  ]
}

For full request structure details (endpoint, headers, base64 encoding, etc.), refer to the Events API docs.

Notes & constraints

• properties is optional, but required for this attribution join.

• If you’re also sending other properties, keep them in the same list (Addressable properties are simple name/value objects).

• (Pixel JS SDK) properties are name/value objects, and there’s a practical cap on how many you should send per event (keep it tight).

• If you'd like to also send your internal user id, please send internal_user_id and reverse user_id for this usage.

Troubleshooting

• ___adrsbl_nonce is missing

  • Confirm the Pixel is installed correctly and firing on that page.

• Events show up, but still not attributed

  • Verify the Events API properties includes { "name": "user_id", "value": "<nonce>" } exactly.

  • Confirm you’re storing and reusing the same nonce value for that user (not generating your own replacement).