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:

Methods

Auth

auth(email, [meta,] callback )

• Authenticates the current session.
• Generates Auth Token to provide to API instances.

Parameters

Example

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

Sync

sync(callback)

• Get user's list of Items
• Requires Auth Token

Parameters

Example

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

Track Item

trackItem (item, callback)

• Capture User's intent to track an Item.
• Returns Response

Parameters

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

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();
});

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

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

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: []