Articles in this section

Using Iterable's JavaScript SDK

This article describes how to use Iterable's JavaScript SDK to send data to Iterable from a web page.

Installation

  1. Create a new JavaScript API key. If possible, we recommend using JWT authentication for additional security.

    WARNING

    Never embed a Standard or Read-only API key in client-side code, whether JavaScript, a mobile app or otherwise.

  2. 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:' == document.location.protocol ? 'https://' : 'http://') + 'js.iterable.com/analytics.js';
    var a = document.getElementsByTagName('script')[0]; a.parentNode.insertBefore(b, a);
})();

  3. (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 about updateCart.

  • trackPurchase(total, [items=[]], [campaignId=null])

    • Tracks a purchase.
    • total is required; items and campaignId are optional.
    • See the note below for more information about trackPurchase.

  • 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="http://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:' == document.location.protocol ? 'https://' : 'http://') + '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.

Related articles

Comments

0 comments

Please sign in to leave a comment.