Abstract

The Cardlytics Embedded SDK is a JavaScript library designed to facilitate the integration of the Cardlytics Platform into partner web and mobile applications. By dynamically creating an embedded iframe and establishing a secure messaging protocol, the SDK enables seamless two-way communication between a partner's backend and the Cardlytics experience. Key features include flexible configuration options, robust access control enforced at the session token level, public accessibility of the SDK script, and support for modern integration practices such as semantic versioning and dynamic caching. The SDK is intended to streamline partner onboarding and ensure secure, up-to-date, and maintainable embedded experiences.

Quickstart

Follow these 3 simple steps to integrate the Cardlytics Embedded SDK into your web application.

Step 1: Get Your Credentials

These will be used to authenticate your backend and initialize the SDK.

Step 2: Create a Secure Backend Endpoint for Session Token

You’ll need to create a backend API that securely calls the Cardlytics session API. This endpoint will be used by the SDK to retrieve a session token.

Backend (Server to Server) call

const express = require('express');
const axios = require('axios');
const router = express.Router();

router.post('/api/get_cardlytics_session', async (req, res) => {
    const payload = {
      client_id: process.env.CARDLYTICS_CLIENT_ID,
      client_secret: process.env.CARDLYTICS_CLIENT_SECRET
    };
    const response = await axios.post(
      'https://publisher-rewards-api.cardlytics.com/v2/session/startSession',
      payload,
      { 'Content-Type': 'application/json' }
    );
    const sessionToken = response.data.sessionToken;
    res.json({ sessionToken, isLoggedIn: true });
});
module.exports = router;

Step 3: Include SDK Script & Initialize on Frontend

Add the Cardlytics SDK to the page where you want to show the embedded experience.

<script src="https://publisher-cdn-us.cardlytics.com/embedding-sdk/v1/cardlytics-embedding-sdk.js">
<script>
    async function getSessionImplementation() {
        // call the api you implemented in step 2
        const response = await fetch('/api/get_cardlytics_session', { method: 'POST' });
        const data = await response.json();
        return data;
    }
    const { open, close } = CardlyticsEmbeddedSDK.create({
        applicationId: 'your_application_id', // get from step 1
        getSession: getSessionImplementation,
    });
    document.getElementById('openBtn').addEventListener("click", function () {
        open(); // attach `open` to a button on your page
    });
</script>

Installation

To enable the embedded experience, include the SDK script on any page that requires CRP access:

<script src="https://publisher-cdn-us.cardlytics.com/embedding-sdk/v1/cardlytics-embedding-sdk.js"></script>

Note: If you use a Content Security Policy (CSP), you may need to add a CSP directive to allow this script to load.

Initialization

Once included, the SDK exposes a global object CardlyticsEmbeddedSDK with a single method: create(config). This method accepts a configuration object (detailed below) and performs the following:

• Dynamically creates an iframe pointing to the embedded CRP experience hosted on a Cardlytics domain.

• Establishes a messaging channel to support interactions (e.g., session token retrieval).

Configuration Options

Return Values

The create method returns an object with:

• show(): Displays the iframe.

• hide(): Hides the iframe.

Access Control

The SDK script is publicly accessible and not restricted by domain. Any website can load it and attempt to call CardlyticsEmbeddedSDK.create() with any applicationId. However, authorization is enforced during the session token retrieval step, preventing unauthorized access.

Customizing the Theme

Partners can personalize the look and feel of their WebSDK integration using a JSON configuration file. Each app ID requires its own config file that includes both system-level and partner-specific settings.

{  
  "name": "Cardlytics Rewards",
  "theme": {
    "colors": {
      "gradientA": "#2196F3",
      "gradientB": "#1E59AF",
      "negative": "#E91B0C",
      "positive": "#27AE60",
      "primary": "#006AC3",
      "warning": "#EC9235"
    },
    "fonts": {
      "body": [
        {
          "url": "https://cdn.prod.website-files.com/64dbb284e8fd858cb428eb8a/64dbb284e8fd858cb428ebc6_CircularStd-Book.woff",
          "weight": "450"
        },
        {
          "url": "https://cdn.prod.website-files.com/64dbb284e8fd858cb428eb8a/64dbb284e8fd858cb428ebd1_CircularStd-Medium.woff",
          "weight": "500"
        },
        {
          "url": "https://cdn.prod.website-files.com/64dbb284e8fd858cb428eb8a/64dbb284e8fd858cb428ebc5_CircularStd-Bold.woff",
          "weight": "700"
        }
      ],
      "headline": [
        {
          "url": "https://cdn.prod.website-files.com/64dbb284e8fd858cb428eb8a/64dbb284e8fd858cb428ebc5_CircularStd-Bold.woff",
          "weight": "700"
        }
      ]
    }
  }
}

What Can Be Customized?

1. Program Name

• Display name shown across the UI
• Example: North Bank Rewards

2. Colors

Customize your integration’s color palette to align with your brand:

• Primary Color
  Used for titles, buttons, and text
  Example: Primary blue shown in the screenshots

• Gradient Colors
  Used in large call-to-action buttons (e.g., $200.00)
  Format: Two HEX values
  Example: ["#123456", "#abcdef"]

• Semantic Colors

  • Success: For checkmark icons or confirmations
  • Error: For expired statuses or errors
  • Warning: Reserved for future use (optional)

3. Font Family

You may provide your own font files to match your brand’s typography:

• Supported font weights: 450, 500, 700
• Accepted formats: .woff, .ttf, etc.
• Fonts will be hosted on our system
• If not provided, browser default sans-serif will be used

4. Partner Icon

• Upload a raw image (recommended: SVG or PNG)
• This will be used as your branded icon in the UI
• We will host the image

5. Screenshots for Reference

6. Submission

• Prepare a JSON config per app ID using the sample structure.
• Include all assets (fonts, icon) if applicable.
• Submit the JSON and assets to your integration manager.

Versioning & Caching

• Versioning: SDK follows Semantic Versioning (SemVer).

• Loading: Partners reference the major version (e.g., /v1/) in their script tag.

• Caching:

  • SDK is served with no-cache, must-revalidate, max-age=0 to ensure freshness.

  • CloudFront handles caching; we perform invalidations when new versions are released.