> For the complete documentation index, see [llms.txt](https://addressable.gitbook.io/knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://addressable.gitbook.io/knowledge-base/event-tracking/addressable-event-api/event-api-attribution/attribution-with-addressable-pixel-recommended.md).

# 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.

{% hint style="info" %}
*If you're using both the Pixel and API, it is generally **always recommended** to follow this guide.*
{% endhint %}

### When is this needed

Use this guide if:

* You already have the [**Addressable Pixel**](/knowledge-base/event-tracking/addressable-pixel.md) installed on your website (via GTM or JS).
* You also send events through the [**Events API**](/knowledge-base/event-tracking/addressable-event-api/events-api-reference.md).
* 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](https://addressable.gitbook.io/knowledge-base/apis/events-api-server-to-server)]:
   * `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

<mark style="background-color:yellow;">**— Step 1 —**</mark>

**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):

```js
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.&#x20;

<mark style="background-color:yellow;">**— Step 2 —**</mark>

**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:

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

<mark style="background-color:yellow;">**— Step 3 —**</mark>

**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](https://addressable.gitbook.io/knowledge-base/apis/events-api-server-to-server))

Add this property to your Events API `data` payload:

```json
"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](https://addressable.gitbook.io/knowledge-base/apis/events-api-server-to-server))

### Example Payload

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

```json
{
  "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](/knowledge-base/event-tracking/addressable-event-api/events-api-reference.md).

### 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).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://addressable.gitbook.io/knowledge-base/event-tracking/addressable-event-api/event-api-attribution/attribution-with-addressable-pixel-recommended.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.