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.

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	Returns a Promise resolving to a valid session token and user login status. Partner must implement this.
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.

Example Integration

<script src="https://publisher-cdn-us.cardlytics.com/embedded-sdk/v1/cardlytics-embedded-sdk.js"></script>
<script>
async function getSessionImplementation() {
  // Partner-specific logic to fetch session token
}

const { show, hide } = CardlyticsEmbeddedSDK.create({
  applicationId: 'YOUR_APPLICATION_ID',
  getSession: getSessionImplementation,
});

// Example: attach to a button
document.getElementById('openBtn').onclick = show;
</script>

Configuration Retrieval

The SDK fetches pre-generated partner-specific configuration from:

https://publisher-cdn-us.cardlytics.com/config/{publisher_guid}/prod/config.js

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.

Messaging Protocol

The embedded SDK communicates with the iframe using the following messages:

Message	Direction	Description
SESSION_REQUEST	Iframe → Parent	Requests a new session token.
SESSION_RESPONSE	Parent → Iframe	Responds with session token and user status.
CLOSE	Iframe → Parent	Instructs the parent to hide the iframe.

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.