> This page is for version 2024-10-01 (default).
> For other versions, use one of these documentation indexes:
> - 2024-10-01 (default): https://docs.getkard.com/2024-10-01/llms.txt
> - Legacy: https://docs.getkard.com/legacy/llms.txt
> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getkard.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getkard.com/_mcp/server.
# Attributions
## Overview
As part of the integration, Kard offers robust solutions for collecting user attribution data for in-app and mobile push notification touchpoints. These data points provide valuable insights into how users interact with your rewards program.
Attribution metrics are increasingly becoming a key requirement among merchants as Kard continues to partner with top-of-wallet, everyday-spend brands. By enabling user attribution data collection, you'll unlock access to more premium offers and drive stronger engagement within your program, ultimately helping you deliver greater value to your users.
## Event Types and Mediums
### Event Types
Kard's attribution system collects two event types:
* **`Impressions`:** Occur anytime a resource (like an offer logo or notification) is *loaded* within your app experience.
*Example:* When a user opens the rewards screen and offers are displayed — each offer loaded generates an `IMPRESSION` event.
See below for a visual representation of an impression event:
* **`Views`:** Occur anytime a user *acts* to view a specific resource.
*Example:* When a user clicks an offer to view its details, or taps on a push notification to open the rewards screen — this generates a `VIEW` event.
See below for a visual representation of a view event:
---
### Mediums
Each event must include a `medium` field to describe where in your experience the event occurred.
**Supported mediums:**
* **`BROWSE`** — User is viewing a list of offers in the rewards experience.
* **`MAP`** — User is exploring offers on a map view.
* **`SEARCH`** — User is viewing or clicking offers as part of a search experience.
* **`PUSH`** — Event occurred within a mobile push notification.
---
## Implementation Methods
Kard supports two integration options for real-time attribution tracking. You may use either, but not both for the same event type:
1. **Event Tracking via Image URLs** — Attribution tracking tokens are included with assets returned by Kard's APIs and webhooks.
2. **Event Tracking via the Attribution API Endpoint** — Provides direct event delivery if your system already tracks impressions and views.
---
## In-App Experiences
### Overview
In-app notifications and offer impressions are tracked when users interact with the rewards experience inside your application.
For **in-app impressions and views**, you can choose **either**:
1. **Image-based tracking**, or
2. **The Attribution API Endpoint**
Use a single method consistently for each event type to prevent duplication.
---
### Option 1: Image-Based Tracking
When loading offers or images from Kard, append the `eventCode` and `medium` parameters to the provided URL.
The images are provided in the [Get Offers by User](https://docs.getkard.com/api/rewards/offers) and [Get Locations by User](https://docs.getkard.com/api/rewards/locations) API endpoints in the `data.attributes.assets.url` fields.
**Example payload:**
```json
GET /v2/issuers/{{organizationId}}/users/{{userId}}/offers
{
"data": {
"attributes": {
...
"assets": [
{
"url": "http://attribution.getkard.com/logos/breakfastbunny_logo.png?subtype=IMG_VIEW&offerId=629fc220b7a4290009a188ec&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZlcnJpbmdQYXJ0bmVyVXNlcklkIjoiNDM4MTAzIiwiaXNzdWVySWQiOiIwMDAwNDMyMSIsInR5cGUiOiJPRkZFUiIsInBheWxvYWQiOnsiand0VGltZXN0YW1wIjoiMjAyNi0wNC0yMyJ9fQ.4f9QmoGpgXVIXu9Tq8XFVcx7Rz0jptsYNYpmaIBszyc&state=eyJyYW5rIjoxLCJmaWx0ZXJzIjpbXX0%3D",
"alt": "",
"type": "IMG_VIEW"
},
{
"url": "https://attribution.getkard.com/public/banners/breakfast-bunny-banner.jpg?subtype=BANNER_VIEW&offerId=629fc220b7a4290009a188ec&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZlcnJpbmdQYXJ0bmVyVXNlcklkIjoiNDM4MTAzIiwiaXNzdWVySWQiOiIwMDAwNDMyMSIsInR5cGUiOiJPRkZFUiIsInBheWxvYWQiOnsiand0VGltZXN0YW1wIjoiMjAyNi0wNC0yMyJ9fQ.4f9QmoGpgXVIXu9Tq8XFVcx7Rz0jptsYNYpmaIBszyc&state=eyJyYW5rIjoxLCJmaWx0ZXJzIjpbXX0%3D",
"alt": "",
"type": "BANNER_VIEW"
},
...
],
...
},
},
}
...
```
User browsing the rewards list → `eventCode=IMPRESSION&medium=BROWSE`
```html
```
User opening an offer detail page upon browsing list → `eventCode=VIEW&medium=BROWSE`
```html
```
User viewing offers on a map → `eventCode=IMPRESSION&medium=MAP`
```html
```
> **Warning**
>
> Do not cache these image URLs. Kard's CDN already handles caching to ensure accurate, real-time tracking.
---
### Option 2: Attribution API Tracking
If you track these events yourself, you can send them directly to Kard via the Attribution API.
Note, in addition to providing an `eventCode` and a `medium` the API requires an `entityId` representing the Kard-provided `offerId` related to the attribution event and an `eventDate` capturing the timestamp the event occurred.
User browsing the rewards list `eventCode=IMPRESSION`, `medium=BROWSE`
```json
POST /v2/issuers/{{organizationId}}/users/{{userId}}/attributions
{
"data": [
{
"type": "offerAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144c075",
"eventCode": "IMPRESSION",
"medium": "BROWSE",
"eventDate": "2025-01-01T00:00:00Z"
}
}
]
}
```
User opening an offer detail page upon a map → `eventCode=VIEW`, `medium=MAP`
```json
POST /v2/issuers/{{organizationId}}/users/{{userId}}/attributions
{
"data": [
{
"type": "offerAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144c075",
"eventCode": "VIEW",
"medium": "MAP",
"eventDate": "2025-01-02T00:00:00Z"
}
}
]
}
```
---
## Mobile Push Notifications
### Overview
Kard supports attribution tracking for **mobile push notifications**, which allows you to measure engagement from the moment a notification is displayed (impression) through to user interaction (view).
For **push notifications**, Kard requires a **hybrid approach**:
* **`IMPRESSION` events:** Must be sent via the **Attribution API**
* **`VIEW` events:** Can be tracked **either** via the **Attribution API** *or* the **image-based tracking method**
---
### Push Notification Impressions
Triggered when a Kard-provided push notification is **displayed** on a user's device. **You must use the attribution API to send push notification impressions.**
Because iOS and Android do not provide a built-in, reliable way to capture notification impressions, this data should be sent on a **best-effort basis**. If your app or SDK can detect when a notification is actually shown (for example, using platform-specific APIs, analytics SDKs, or Firebase Cloud Messaging), use that signal to send the impression event.
If such tracking is not available, please instead send the event when the push notification is **sent** to the device.
---
### What Works Best
Use your existing notification or analytics SDKs (e.g., Firebase Cloud Messaging or other in-app event trackers) to detect when a push notification is **actually displayed** on the user's device. When available, this provides the most accurate impression data.
### What to Do Instead
If you do **not** have tools or SDKs capable of detecting impressions, you can still participate in attribution by sending an impression event when the notification is **sent** to the device.
This data collection helps Kard approximate impressions that were sent to the user when display data isn't available, without requiring any extra SDKs or configuration.
User's lock screen displays a push notification for an earned reward → `eventCode=IMPRESSION`, `medium=PUSH`
Note: in addition to `eventCode` and a `medium` the API requires an `entityId` representing the Kard-provided `notificationId` related to the attribution event and an `eventDate` capturing the timestamp the event occurred.
```json
POST /v2/issuers/{{organizationId}}/users/{{userId}}/attributions
{
"data": [
{
"type": "notificationAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144a623",
"eventCode": "IMPRESSION",
"medium": "PUSH",
"eventDate": "2025-01-06T00:00:00Z"
}
}
]
}
```
---
### Push Notification Views
Triggered when a user **clicks** on a push notification and opens the app or relevant reward experience. You can choose **either** of the following implementations:
### Option 1: Image-Based Tracking
The blank image pixel is included in the relevant notification webhooks within the `data.attributes.attributionUrl` field. To use it, append the `eventCode` and `medium` parameters to the provided URL.
**Example payload:**
```json
{
"data": {
"attributes": {
"attributionUrl": "https://attribution.getkard.com/public/logos/transparent.png?token=valid.signed.jwt",
...
},
...
},
...
}
```
User clicks into push notification and opens into app → `eventCode=VIEW`, `medium=PUSH`
```html
```
### Option 2: Attribution API
If you track these events yourself, you can send them directly to Kard via the Attribution API.
User clicks into push notification and opens into app → `eventCode=VIEW`, `medium=PUSH`
Note: in addition to `eventCode` and a `medium` the API requires an `entityId` representing the Kard-provided `notificationId` related to the attribution event and an `eventDate` capturing the timestamp the event occurred.
```json
POST /v2/issuers/{{organizationId}}/users/{{userId}}/attributions
{
"data": [
{
"type": "notificationAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144c178",
"eventCode": "VIEW",
"medium": "PUSH",
"eventDate": "2025-01-07T00:00:00Z"
}
}
]
}
```
---
## Best Practices
* **In-app experiences:** Use either Image-based tracking or the API for both event types.
* **Push Notification Impressions:** Must be sent via the Attribution API.
* **Push Notification Views:** Use either Image-based tracking or the API.
* Use **either** Image-based tracking **or** the Attribution API per event type — not both.
* Avoid caching attribution URLs if you choose to use the Image-based tracking.
* Send all API-based events promptly for real-time data accuracy.