Appboy Module: appboy

This is the public interface for the Appboy Web SDK. To get started right away, put the following snippet inside the <head> section of your page to load it dynamically:

+function(a,p,b,y) {
  (y = a.createElement(p)).type = 'text/javascript';
  y.src = 'https://js.appboycdn.com/web-sdk/0.0/appboy.min.js';
  (c = a.getElementsByTagName(p)[0]).parentNode.insertBefore(y, c);
  y.onload = y.onreadystatechange = b;
}(document, 'script', function() {
  appboy.initialize('YOUR-API-KEY-HERE', { enableLogging: true });
  appboy.openSession();
});

This will provide a global variable named appboy that you can use to send data to the Appboy API. Note that { enableLogging: true } will cause Appboy to log to the javascript console, which is visible to all users! You should probably remove this or provide an alternate logger with appboy.setLogger() before you release your page to production.

Alternately, you can use RequireJS or another AMD module-loader to load https://js.appboycdn.com/web-sdk/0.0/appboy.min.js. For example:

require(['https://js.appboycdn.com/web-sdk/0.0/appboy.min.js'], function(appboyModule) {
  appboyModule.initialize('YOUR-API-KEY-HERE', { enableLogging: true });
  appboyModule.openSession();
});

Methods

<static> changeUser(userId)

When you first start using Appboy on a device, the user is considered "anonymous". You can use this method to optionally identify a user with a unique ID, which enables the following:

If the same user is identified on another device, their user profile, usage history and event history will be shared across devices.
If your app is used by multiple people, you can assign each of them a unique identifier to track them separately. Only the most recent user on a particular device will receive push notifications and in-app messages.

When you request a user switch (which is any call to changeUser where the new user ID is not the same as the existing user ID), the current session for the previous user (anonymous or not) is automatically ended and a new session is started. Similarly, following a call to changeUser, any events which fire are guaranteed to be for the new user -- if an in-flight server request completes for the old user after the user switch no events will fire, so you do not need to worry about filtering out events from Appboy for old users.

Additionally, if you identify a user which has never been identified on another device, the entire history of that user as an "anonymous" user on this device will be preserved and associated with the newly identified user. However, if you identify a user which has been identified in another app, any history which was already flushed to the server for the anonymous user on this device will become orphaned and will not be associated with any future users. These orphaned users are not considered in your user counts and will not be messaged.

Note: Once you identify a user, you cannot revert to the "anonymous" user. The transition from anonymous to identified tracking is only allowed once because the initial anonymous user receives special treatment to allow for preservation of their history. As a result, we recommend against changing the user ID just because your app has entered a "logged out" state because it makes you unable to target the previously logged out user with re-engagement campaigns. If you anticipate multiple users on the same device, but only want to target one of them when your app is in a logged out state, we recommend separately keeping track of the user ID you want to target while logged out and switching back to that user ID as part of your app's logout process.

Parameters:

Name	Type	Description
`userId`	string	A unique identifier for this user.

<static> destroy()

Destroys this appboy instance, releasing member variables which retain memory.

<static> getUser() → {ab.User}

Returns:

The user currently being tracked by Appboy, used for querying the tracked user id and setting user attributes. Should only be accessed via the getUser() function.

Type: ab.User

<static> initialize((string), (object))

Initializes this appboy instance with your API key. This method must be called before other Appboy methods are invoked, and is part of the default loading snippets. Subsequent calls will be ignored until destroy is called.

Parameters:

Name	Type	Description
`(string)`		apiKey - Your app's Appboy API Key. Your API keys can be found at https://dashboard.appboy.com/app_settings/app_settings
`(object)`		options - Optional configuration options. Supported options: enableLogging - set to true to enable logging by default

<static> logCustomEvent(eventName, eventProperties) → {boolean}

Reports that the current user performed a custom named event.

Parameters:

Name	Type	Description
`eventName`	string	The identifier for the event to track. Best practice is to track generic events useful for segmenting, instead of specific user actions (i.e. track watched_sports_video instead of watched_video_adrian_peterson_td_mnf). Value is limited to 255 characters in length, cannot begin with a $, and can only contain alphanumeric characters and punctuation.
`eventProperties`	object	Optional hash of properties for this event. Keys are limited to 255 characters in length, cannot begin with a $, and can only contain alphanumeric characters and punctuation. Values can be numeric, boolean, Date objects, or strings 255 characters or shorter.

Returns:

Whether or not the event was successfully attached to the session (to be flushed later).

Type: boolean

<static> logPurchase(productId, price, currencyCode, quantity, purchaseProperties) → {boolean}

Reports that the current user made an in-app purchase. Useful for tracking and segmenting users.

Parameters:

Name	Type	Description
`productId`	string	A string identifier for the product purchased, e.g. an SKU. Value is limited to 255 characters in length, cannot begin with a $, and can only contain alphanumeric characters and punctuation.
`price`	float	The price paid. Base units depend on the currency. As an example, USD should be reported as Dollars.Cents, whereas JPY should be reported as a whole number of Yen. All provided values will be rounded to two digits with toFixed(2)
`currencyCode`	string	Currencies should be represented as an ISO 4217 currency code. Supported currency symbols include: BRL, CAD, CZK, CHF, DKK, EUR, GBP, HKD, HUF, ILS, INR, JPY, KRW, MXN, NOK, NZD, PLN, RUB, SEK, SGD, TWD and USD. Any other provided currency symbol will result in a logged warning and no other action taken by the SDK. Optional - defaults to USD if not provided.
`quantity`	integer	The quantity of items purchased expressed as a whole number. Must be at least 1 and at most 100. Optional - defaults to 1 if not provided.
`purchaseProperties`	object	Optional hash of properties for this purchase. Keys are limited to 255 characters in length, cannot begin with a $, and can only contain alphanumeric characters and punctuation. Values can be numeric, boolean, Date objects, or strings 255 characters or shorter.

Returns:

Whether or not the purchase was successfully attached to the session (to be flushed later).

Type: boolean

<static> openSession()

Opens a new session, or resumes the previous session if this browser had activity within the last 30 minutes.

<static> requestImmediateDataFlush()

By default, data logged to Appboy through the SDK is queued locally (in HTML 5 localStorage when available, and in memory otherwise) and sent to Appboy's servers asynchronously on a regular 10-second interval. This is done to optimize network usage and provide resiliancy against network or server outages. This method bypasses the 10-second interval and immediately flushes queued data.

<static> setLogger(loggerFunction)

By default, Appboy logs to the browser console. Call this method to set a custom log action.

Parameters:

Name	Type	Description
`loggerFunction`	function	A function to invoke with log messages. Should accept a single string parameter for message.

<static> toggleAppboyLogging()

By default, Appboy silences its logging to prevent spamming production js consoles. Call this method to toggle logging.