This article describes how to use Iterable's JavaScript SDK to send data to Iterable from a web page.
Installation
-
Create a new JavaScript API key.
WARNINGS
- Never embed a server-side or read-only API key in client-side code, whether JavaScript, a mobile app or otherwise.
- Iterable's JavaScript SDK does not support JWT-enabled API keys.
-
On each web page from which you'd like to track Iterable events, include the following code before the
</body>
tag. This allows you to call the methods described below.(function () { var b = document.createElement('script'); b.type = 'text/javascript'; b.async = true; b.src = 'https://js.iterable.com/analytics.js'; var a = document.getElementsByTagName('script')[0]; a.parentNode.insertBefore(b, a); })();
-
(Optional) Include the IterableUtils library:
<script type="text/javascript" src="https://js.iterable.com/iterableUtils.js"/>
IterableUtils is optional, but it contains some basic convenience utilities for URI query string parsing and working with cookies.
SDK methods
Iterable's JavaScript SDK provides the following methods:
-
account(API_KEY, [endpoint="https://api.iterable.com"])
- Sets the API key the JavaScript SDK will use when communicating with Iterable.
identify(email, [data={}])
- Sets the user.track(eventName, [data={}])
- Track an event.updateCart(items)
- Track updates to a user's cart. See the note below for more information aboutupdateCart
.trackPurchase(total, [items=[]], [campaignId=null])
- Tracks a purchase.total
is required;items
andcampaignId
are optional. See the note below for more information abouttrackPurchase
.push('account'|'identify'|'track', ...)
- Use this method (instead of the others) if you're not sure whether the SDK has loaded. See the example SDK usage below.
NOTE
For updateCart
and trackPurchase
, each item should be in the following
form:
var item = { id: string, // a unique id for this item sku: string, // OPTIONAL name: string, // the item's name description: string, // OPTIONAL categories: list[string], // OPTIONAL price: number, // the per unit price of this item quantity: int, // how many of these items were purchased imageUrl: string, // OPTIONAL url: string, // OPTIONAL dataFields: JsonObject // OPTIONAL }
Example
The following example demonstrates how to use the JavaScript SDK to identify a user and track a custom event (and some data that describes it):
<html> <body> <!-- Optional; provides methods for query string parsing and working with cookies --> <script type="text/javascript" src="https://js.iterable.com/iterableUtils.js"></script> <!-- Enter an email address, then click the button to track an event --> Email Address: <input type="text" id="email" /> <button type="button" onclick="identifyUser()">Identify User</button> <button type="button" onclick="trackEvent()">Track MyButtonClickedEvent</button> <script> var _iaq = _iaq || []; var click = 0; // Identify the user and set some fields on their Iterable profile function identifyUser() { _iaq.push(['identify', document.getElementById('email').value, { "MyField": "Testing", "MyField2": 123 }]); } // Track a click event, passing a click count (from the current session) // that will be stored in the event's dataFields property function trackEvent() { _iaq.push(['track', 'MyButtonClickedEvent', { "clickNumber": ++click }]); } // Replace <API key> with an Iterable API key (of type JavaScriptSDK) _iaq.push(['account', '<API key>']); (function () { var b = document.createElement('script'); b.type = 'text/javascript'; b.async = true; b.src = 'https://js.iterable.com/analytics.js'; var a = document.getElementsByTagName('script')[0]; a.parentNode.insertBefore(b, a); })(); </script> </body> </html>
WARNING
- Ad blockers and some browsers can prevent JavaScript from loading.
- The JavaScript SDK does not provide response codes or retry logic.
Comments
0 comments
Please sign in to leave a comment.