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/linking-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/embedded-sdk/v1/cardlytics-embedded-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

Key	Type	Required	Description
applicationId	String	Yes	Unique identifier (GUID) for the partner environment. Passed via query string to the embedded experience.
getSession	Function	Yes	The publisher must wrap our /startSession endpoint within their own authentication endpoint. Then, they need to pass a function to the SDK's getSession method. This function should call the publisher’s endpoint, which in turn calls our /startSession endpoint.
autoOpen	Boolean	No	If true, the iframe opens immediately. Useful for mobile webviews.
onShow	Function	No	Callback triggered when the experience is shown.
onHide	Function	No	Callback triggered when the experience is hidden.

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

Publishers can customize the SDK experience to match their brand by providing configuration details to our team. Currently, the following elements can be customized:

Primary Color: Sets the main color used across the SDK UI.

Experience Title: Custom display title shown to end users.

More customization options will be added over time. Please reach out to the integration team to update or request changes to your configuration.

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.