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.

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

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

3. 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 and Get Locations by User API endpoints in the data.attributes.assets.url fields.

Example payload:

1
GET /v2/issuers/{{organizationId}}/users/{{userId}}/offers
2
{
3
  "data": {
4
    "attributes": {
5
	    ...
6
      "assets": [
7
        {
8
          "type": "LOGO_IMAGE",
9
          "url": "https://attribution.getkard.com/image.jpg?token=valid.signed.jwt",
10
          "alt": "Worlds Greatest Chicken Logo Image"
11
        },
12
        {
13
          "type": "BANNER_IMAGE",
14
          "url": "https://attribution.getkard.com/image.jpg?token=valid.signed.jwt",
15
          "alt": "Worlds Greatest Chicken Banner Image"
16
        }
17
        ...
18
      ],
19
      ...
20
    },
21
  },
22
}
23
...

User browsing the rewards list → eventCode=IMPRESSION&medium=BROWSE

1
<img src="https://attribution.getkard.com/image.jpg?token=valid.signed.jwt&eventCode=IMPRESSION&medium=BROWSE"/>

User opening an offer detail page upon browsing list → eventCode=VIEW&medium=BROWSE

1
<img src="https://attribution.getkard.com/image.jpg?token=valid.signed.jwt&eventCode=VIEW&medium=BROWSE" />

User viewing offers on a map → eventCode=IMPRESSION&medium=MAP

1
<img src="https://attribution.getkard.com/image.jpg?token=valid.signed.jwt&eventCode=IMPRESSION&medium=MAP" />

⚠️ 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

1
POST /v2/issuers/{{organizationId}}/users/{{userId}}/attributions
2
{
3
  "data": [
4
    {
5
      "type": "offerAttribution",
6
      "attributes": {
7
        "entityId": "60e4ba1da31c5a22a144c075",
8
        "eventCode": "IMPRESSION",
9
        "medium": "BROWSE",
10
        "eventDate": "2025-01-01T00:00:00Z"
11
      }
12
    }
13
  ]
14
}

User opening an offer detail page upon a map → eventCode=VIEW, medium=MAP

1
POST /v2/issuers/{{organizationId}}/users/{{userId}}/attributions
2
{
3
  "data": [
4
    {
5
      "type": "offerAttribution",
6
      "attributes": {
7
        "entityId": "60e4ba1da31c5a22a144c075",
8
        "eventCode": "VIEW",
9
        "medium": "MAP",
10
        "eventDate": "2025-01-02T00:00:00Z"
11
      }
12
    }
13
  ]
14
}

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

1
POST /v2/issuers/{{organizationId}}/users/{{userId}}/attributions
2
{
3
  "data": [
4
    {
5
      "type": "notificationAttribution",
6
      "attributes": {
7
	      "entityId": "60e4ba1da31c5a22a144a623",
8
        "eventCode": "IMPRESSION",
9
        "medium": "PUSH",
10
        "eventDate": "2025-01-06T00:00:00Z"
11
      }
12
    }
13
  ]
14
}

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:

1
{
2
  "data": {
3
    "attributes": {
4
	    "attributionUrl": "https://attribution.getkard.com/public/logos/transparent.png?token=valid.signed.jwt",
5
      ...
6
    },
7
    ...
8
  },
9
  ...
10
}

User clicks into push notification and opens into app → eventCode=VIEW, medium=PUSH

1
<img src="https://attribution.getkard.com/public/logos/transparent.png?token=valid.signed.jwt&eventCode=VIEW&medium=PUSH" />

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.

1
POST /v2/issuers/{{organizationId}}/users/{{userId}}/attributions
2
{
3
  "data": [
4
    {
5
      "type": "notificationAttribution",
6
      "attributes": {
7
        "entityId": "60e4ba1da31c5a22a144c178",
8
        "eventCode": "VIEW",
9
        "medium": "PUSH",
10
        "eventDate": "2025-01-07T00:00:00Z"
11
      }
12
    }
13
  ]
14
}

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