MyAlerts

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:

Name Type Description
clientId String Client id, provided by MyAlerts.
token String Auth Token returned from call to auth()
userAgent String User agent metadata
requestsTimeout Number Timeout for requests, in milliseconds.

Methods

Auth

auth(email, [meta,] callback )

Parameters

Name Type Description
email String Email address of the current user
meta Object Metadata associated with the request
callback Function Returns Response containing Auth Token

Example

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

Sync

sync(callback)

Parameters

Name Type Description
callback Function Returns 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

Name Type Description
item Object The Item to track
callback Function Returns 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

Name Type Description
item Object The Item to untrack
callback Function Returns 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();
});
Name Type Description
item Object The Item to remove
callback Function Returns 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

Name Type Description
item Boolean Response success or failure
status String API response status code
code Number HTTP response status code
message String API response message
data Object API 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

Name Type Description
url String URL of Item
type String Type of Item. Options: product, product_search
meta Object Meta 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: []

Updated about 13 hours ago

JavaScript


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.