JavaScript

API-JS

A JavaScript consumer of the MyAlerts Snap API.

Install

npm login
# enter valid npm credentials
npm install @trackif/api-js --save

Initialize

Create an API instance.

var Api = require('@trackif/api-js');
var options = {
    clientId: 'myclientid',
    token: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJzbmFwIiwiZGF0YSI6Intc...',
    userAgent: '5.0 (Macintosh; Intel Mac OS X 10_12_2) AppleWebKit...',
    requestTimeout: 30000
};
var api = new Api(options);

Options object properties to initialize an API instance:

NameTypeDescription
clientIdStringClient id, provided by MyAlerts.
tokenStringAuth Token returned from call to auth()
userAgentStringUser agent metadata
requestsTimeoutNumberTimeout for requests, in milliseconds.

Methods

Auth

auth(email, [meta,] callback )

Parameters

NameTypeDescription
emailStringEmail address of the current user
metaObjectMetadata associated with the request
callbackFunctionReturns Response containing Auth Token

Example

api.auth(email, {}, function (err, response) {
    if (err) return handleError(err);
    handleSuccess(response);
});

Sync

sync(callback)

Parameters

NameTypeDescription
callbackFunctionReturns Response containing User's list of Items

Example

api.sync(function (err, response) {
    if (err) return handleError(err);
    handleSync(response);
});

Track Item

trackItem (item, callback)

Parameters

NameTypeDescription
itemObjectThe Item to track
callbackFunctionReturns Response

Example

var item = {
    url: window.location.href,
    type: 'product',
    meta: {
        offers: true,
        newsletter: false
    },
    tags: 'product-favorite',
    triggers: []
};

api.trackItem(item, function (err) {
    if (err) return handleError(err);
    handleTrackItemSuccess();
});

Untrack Item

untrackItem(item, callback)

  • Capture User's intent to untrack an Item

Parameters

NameTypeDescription
itemObjectThe Item to untrack
callbackFunctionReturns Response

Example

var item = getItem();

api.untrackItem(item, function (err) {
    if (err) return handleError(err);
    handleUntrackItemSuccess();
});

Remove Item

removeItem(item, callback)

  • Remove an Item from the users track list.

Example

var item = getItem();

api.removeItem(item, function (err) {
    if (err) return handleError(err);
    handleTrackItemSuccess();
});
NameTypeDescription
itemObjectThe Item to remove
callbackFunctionReturns Response

Definitions

Auth Token

JSON Web Token(JWT) returned from Auth. Store this token in the browser for subsequent calls to the Snap API.

User

Visitor with a current browser session. Must have an Auth token to sync, track, untrack, or remove intent.

Response

Response object returned from all API calls.

Properties

NameTypeDescription
itemBooleanResponse success or failure
statusStringAPI response status code
codeNumberHTTP response status code
messageStringAPI response message
dataObjectAPI response data

Item

JSON serializable object passed to all tracking methods. An Item is identified by a unique url, representing a product, job, event, search, category, etc.

Properties

NameTypeDescription
urlStringURL of Item
typeStringType of Item. Options: product, product_search
metaObjectMeta data associated with Request
tags[String]Tags associated with Request
triggers[Object]Triggers to apply to the Request

url

Url structures for your Items must be consistent, and should contain only parameters needed to identify the specific product.

If the Item to track has variant data (e.g. size, color), then you should create a url that correlates to that item and variant combination. e.g. http://example.com/p/cool-product.html?size=10&color=red.

All unique url's will show up as distinct Items to track, therefore variable parameters on your URL should be removed when creating an Item url. We strongly recommend using urijs to help craft your urls.

type

  • product Item type is a product.
  • product_search Item type is a product search.

meta

A JSON serializable object, with arbitrary property values. This value will be returned with Item Lists on sync requests. May be used for additional reporting data.

tags

An array of descriptive attributes associated with an Item. You may have multiple triggers per Item.

Use Tags to correlate User intent with sets of Triggers. For instance, a User may track a 'price-drop' on an Item, want alerts when an Item is 'back-in-stock', or want to know when 'new-similar-items' are available.

Returned with sync requests.

triggers

An array of actions describing how a User's wants to track an Item. You may have multiple triggers per Item.

Use triggers to setup future actions based on User's intent. Custom trigger types are available upon request.

Tagsets

Tagsets represent pairings of Tags and Triggers. Though they have no direct relationship and act independently, use them together to help simplify tracking intent.

Recommended Tags + Triggers

The following Item properties match the tagsets used by the MyAlerts Snap UI.

Alert User when an Item is back-in-stock:
tags: ['availability'],
triggers: [{
    name: 'product_availability'
}]
Alert User when an Item price changes:
tags: ['price-drop'],
triggers: [{
    name: 'product_price_change',
    options: {
        conditions: [{
            name: 'price_drop',
            threshold_type: 'percentage', // Options: 'percentage', 'fixed'. Default 'percentage'
            threshold: 2 // Default 2
        }]
    }
}]

If threshold_type = percentage, the threshold is in percent. The price drop will trigger an alert when the percent drop is more than this percent.

If threshold_type = fixed, the threshold is a fixed dollar amount. The price drop will trigger an alert when the percent drop is more than this dollar amount.

Alert User with recommendations when a product is permanently out-of-stock:
tags: ['permanent-00s'],
triggers: [{
    name: 'product_permanent_out_of_stock',
    conditions: {
        threshold: 21 // Number of days product is out-of-stock before considered permanent. Default: 21 days
    }
}]
Alert User when new Items are added to the tracked search or category:
tags: ['new-items'],
triggers: [{
    name: 'product_search_list_update',
    options: {
        detectable: [
            'entry_added' // Options: 'entry_added', 'entry_removed'
        ]
    }
}]
Alert User when new Jobs are added to the tracked search or category:
tags: ['new-jobs'],
triggers: [{
    name: 'job_search_list_update',
    options: {
        detectable: [
            'entry_added' // Options: 'entry_added', 'entry_removed'
        ]
    }
}]
Alert User when registry changes occur:
tags: ['registry'],
triggers: [
    {
        name: 'registry_availability',
        options: {}
    }, {
        name: 'registry_entry_update',
        options: {}
    }, {
        name: 'registry_few_items_remaining',
        options: {
            min: 1
        }
    }, {
        name: 'registry_list_update',
        options: {
            detectable: [
                'entry_added' // Options: 'entry_added', 'entry_removed'
            ]
        }
    }, {
        name: 'registry_price_change',
        options: {
            conditions: [{
                name: 'price_drop'
            }]
        }
    }, {
        name: 'registry_purchase',
        options: {}
    }
]
Mark Item as a favorite of the User:
tags: ['favorite'],
triggers: []