Amplitude JS SDK Iframe Client

A tiny-ish package to perform cross-domain communication between a website and an iframe with Amplitude JS SDK.

Check out a basic demo here.

Table of Contents

• Amplitude JS SDK Iframe Client
• Table of Contents
• Motivation
• Installation
• Usage
• Contributing
• License

Motivation

You might be wondering - why would someone have to use Amplitude SDK through an iframe? The answer is simple - security policies. Some organizations require their websites to not execute arbitary code capable of tracking users and making requests (despite this code being certified). But as a business you might benefit from using a tool like Amplitude, so as a compromise arbitary code is executed on a different cookie-less domain which doesn't violate security policies.

Currently only the most basic functionality is available: initializing multiple projects in the same or multiple iframes, associating users by id and setting their properties. Identify and Revenue functionality is not supported at the moment.

setUserProperties should cover every need to interact with Identify since it's just a shortcut for it.

Installation

You can install amplitude-js-iframe using npm or yarn:

npm i amplitude-js-iframe --save
# or
yarn add amplitude-js-iframe

But that's not all: to properly communcate you also need an iframe. See HTML file for a possible implementation. Or just embed the code from script.js after SDK snippet in your own document.

Usage

See an example in the demo or discover example code yourself at gh-pages branch.

This package exports AmplitudeIframeClient class which mostly duplicates parts of the interface from Amplitude class from JS SDK with primary difference being the absence of callbacks.

For example, you may get an instance of the client using getInstance static method:

import { AmplitudeIframeClient } from "amplitude-js-iframe";

AmplitudeIframeClient.getInstance("instance_name")
// or use the default instance
AmplitudeIframeClient.getInstance()

After creating an instance you should initialize it using init function. The notable difference from SDK here is that it takes another parameter in front: a MessagePort to communcate with an iframe. Why a MessagePort you might ask - in order to allow communicating not only with iframes, but also with ServiceWorkers and NodeJS MessagePort. In order to help you get the desired iframe this package also exports a helper method getIframeMessagePort.

import {
  AmplitudeIframeClient,
  getIframeMessagePort,
} from "amplitude-js-iframe";

// pass iframe selector as the argument
const iframeMp = await getIframeMessagePort("#iframe");
AmplitudeIframeClient.getInstance().init(
  iframeMp,
  "<API_KEY_HERE>"
  // optionally specify other parameters
);

From this point you may start sending events, assigning user properties and ID.

import { AmplitudeIframeClient } from "amplitude-js-iframe";

AmplitudeIframeClient.getInstance().logEvent("test", {
  hello: "world",
  quick: ["brown", "fox"],
});

AmplitudeIframeClient.getInstance().setUserId("123");

AmplitudeIframeClient.getInstance().setUserProperties({ role: "anon" });

Contributing

Feel free to send any suggestions in GitHub issues or open a Pull Request with your feature.

License

MIT