Instantiate SDK
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.
-
Updated 1 day ago