Appboy Module: appboy

This is the public interface for the Appboy Web SDK. To get started right away, check out our Web SDK github repository.

Methods

<static> changeUser(userId)

When a user first uses Appboy on a device they are considered "anonymous". Use this method to 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 on the same browser by multiple people, you can assign each of them a unique identifier to track them separately. Only the most recent user on a particular browser 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, destroying all subscription callbacks and releasing member variables which retain memory.

<static> getCachedFeed() → {ab.Feed}

Get all unexpired cards from the last news feed refresh.

Returns:

A ab.Feed object which includes all unexpired ab.Card objects from the last news feed refresh.

Type: ab.Feed

<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(apiKey, options)

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	Argument	Description
`apiKey`	string		Your app's Appboy API Key. Your API keys can be found here.
`options`	object	<optional>	Optional configuration options. Supported options: `enableLogging` - Set to true to enable logging by default. Note that this 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. `sessionTimeoutInSeconds` - By default, sessions time out after 30 minutes of inactivity. Provide a value for this configuration option to override that default with a value of your own. `doNotLoadFontAwesome` - Appboy uses FontAwesome for in-app message icons. By default, Appboy will automatically load FontAwesome from `https://maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css`. To disable this behavior (e.g. because your site uses a customized version of FontAwesome), set this option to `true`. Note that if you do this, you are responsible for ensuring that FontAwesome is loaded on your site - otherwise in-app messages may not render correctly.

<static> isAppboyPushSupported() → {boolean}

Currently, Appboy only supports web push for Google Chrome. This method allows you to programmatically determine whether to show push-related user interface elements to the user.

Returns:

Whether or not push is supported in this environment.

Type: boolean

<static> logCardClick(card) → {boolean}

Logs that the user clicked the given card. This is done automatically when the user clicks on a card generated by appboy.display.showFeed, and should only be called if you're bypassing that method and manually displaying the feed in your own code.

Parameters:

Name	Type	Description
`card`	string	the ab.Card object that received a click

Returns:

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

Type: boolean

<static> logCardImpressions(cards) → {boolean}

Logs that the user saw the given cards. This is done automatically when you use appboy.display.showFeed, and should only be called if you're bypassing that method and manually displaying the feed in your own code.

Parameters:

Name	Type	Description
`cards`	Array	array of ab.Card objects that received impressions

Returns:

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

Type: boolean

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

Reports that the current user performed a custom named event.

Parameters:

Name	Type	Argument	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> logFeedDisplayed()

Logs that the news feed was displayed. This is done automatically when you use appboy.display.showFeed, and should only be called if you're bypassing that method and manually displaying the feed in your own code.

<static> logInAppMessageButtonClick(button, inAppMessage) → {boolean}

Logs that the user clicked the given in-app message button. This is done automatically when the user clicks on a button in a message generated by appboy.display.showInAppMessage, and should only be called if you're bypassing that method and manually displaying the message in your own code.

Parameters:

Name	Type	Description
`button`	ab.InAppMessage.Button	The button clicked
`inAppMessage`	ab.InAppMessage	The message this button belongs to

Returns:

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

Type: boolean

<static> logInAppMessageClick(inAppMessage) → {boolean}

Logs that the user clicked the given in-app message. This is done automatically when the user clicks on a message generated by appboy.display.showInAppMessage, and should only be called if you're bypassing that method and manually displaying the message in your own code.

Parameters:

Name	Type	Description
`inAppMessage`	ab.InAppMessage

Returns:

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

Type: boolean

<static> logInAppMessageImpression(inAppMessage) → {boolean}

Logs that the user saw the given in-app message. This is done automatically when you use appboy.display.showInAppMessage, and should only be called if you're bypassing that method and manually displaying the message in your own code.

Parameters:

Name	Type	Description
`inAppMessage`	ab.InAppMessage

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	Argument	Default	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	<optional>	USD	Currencies should be represented as an ISO 4217 currency code. Supported currency symbols include: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTC, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, IQD, IRR, ISK, JEP, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MTL, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, STD, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEF, VND, VUV, WST, XAF, XAG, XAU, XCD, XDR, XOF, XPD, XPF, XPT, YER, ZAR, ZMK, ZMW, and ZWL. Any other provided currency symbol will result in a logged warning and no other action taken by the SDK.
`quantity`	integer	<optional>	1	The quantity of items purchased expressed as a whole number. Must be at least 1 and at most 100.
`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. Refreshes In-App Messages if they have not been refreshed for this user in the last 10 minutes.

<static> registerAppboyPushMessages()

Attempt to register this browser environment to receive web pushes for this user. Currently only GCM pushes to Attempt to register this browser environment to receive web pushes for this user. Currently only GCM pushes to Google Chrome are supported. Please refer to Chrome's best practices for user experience guidance on when to call this method. If push is supported and the user is not already subscribed, this method will immediately request push permission from the user.

In order to properly use this feature, there are some integration steps required on your end:

Copy https://js.appboycdn.com/web-sdk/1.1/service-worker.js into the root directory of your website.
Add <link rel="manifest" href="/manifest.json" /> in your <head> section
Create a manifest.json file with the JSON content below, and place it in the root directory of your website:

{
  "gcm_user_visible_only": true,
  "gcm_sender_id": "123456789012" // Your GCM Project Number
}

Note that you'll have to replace "gcm_sender_id" with your own GCM Project Number available from the Google Developers Console (You can follow Google's instructions for creating an API Project if you don't already have one).

<static> removeAllSubscriptions()

Remove all event subscriptions.

<static> removeSubscription(subscriptionGuid)

Remove an event subscription that you previously subscribed to.

Parameters:

Name	Type	Description
`subscriptionGuid`	string	The identifier of the subscription you wish to remove, returned by the method you initially used to create it.

<static> requestFeedRefresh()

Requests an immediate refresh of the news feed from Appboy servers. By default, the news feed is refreshed on appboy.display.showFeed (when stale - see appboy.display.showFeed for details). If you want to refresh the feed from the server at another time you must call this function. Results of this refresh are reported asynchronously to subscriptions created via subscribeToFeedUpdates.

<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> requestInAppMessageRefresh(count)

Requests an immediate refresh of available in-app messages from Appboy servers. By default, in-app messages are refreshed at most every 10 minutes on openSession, and if you want to refresh new messages from the server at another time you must call this function.

Parameters:

Name	Type	Argument	Default	Description
`count`	integer	<optional>	1	Maximum number of in-app messages to retrieve. Pass -1 to retrieve all available in-app messages. In-app messages are only retrieved for a given user from the server once, so be sure you can handle all retrieved messages before page close or they will be lost for this user. Pass 0 to avoid a server refresh entirely and invoke your subscribers from subscribeToNewInAppMessages with previously unhandled messages.

<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> subscribeToFeedUpdates(subscriber) → {string}

Subscribe to news feed updates. The subscriber callback will be called whenever the news feed is updated.

Parameters:

Name	Type	Description
`subscriber`	function	The callback function to handle new in-app messages. This function will be called with a ab.Feed object which includes all ab.Card objects currently in the feed.

Returns:

The identifier of the subscription created. This can be passed to removeSubscription to cancel the subscription.

Type: string

<static> subscribeToNewInAppMessages(subscriber) → {string}

Subscribe to receive in-app messages. The subscriber callback will be called whenever new in-app messages are received. If you are using the build of Appboy's library with UI, the most basic usage of this would be

appboy.subscribeToNewInAppMessages(function(inAppMessages) {
  appboy.display.showInAppMessage(inAppMessages[0]);
  return inAppMessages.slice(1);
});

Parameters:

Name	Type	Description
`subscriber`	function	The callback function to handle new in-app messages. This function will be called with an array of all currently unhandled ab.InAppMessage objects. If you are using the build of Appboy's library with UI, you may wish to call appboy.display.showInAppMessage with one or more in-app messages. This function should return an array of any in-app messages that you wish to remain unhandled and retained until the next time subscriber is called.

Returns:

The identifier of the subscription created. This can be passed to removeSubscription to cancel the subscription.

Type: string

<static> toggleAppboyLogging()

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

<static> unregisterAppboyPushMessages()

Unregisters the environment from receiving push notifications from Appboy