Class Iterable

The main class for the Iterable React Native SDK.

The majority of the high-level functionality can be accomplished through the static methods of this class. EG: initializing the SDK, logging in a user, tracking purchases, etc.

Example

// Initialize the SDK
Iterable.initialize(YOUR_API_KEY, new IterableConfig());

// Log in a user
Iterable.setEmail('my.email@company.com');
// OR
Iterable.setUserId('myUserId');

Constructors

constructor

new Iterable(): Iterable
Returns Iterable

Properties

`Static`logger

logger: IterableLogger = ...

Logger for the Iterable SDK Log level is set with IterableLogLevel

`Static`savedConfig

savedConfig: IterableConfig = ...

Current configuration of the Iterable SDK

Accessors

`Static`inAppManager

get inAppManager(): undefined | IterableInAppManager
In-app message manager for the current user.

This property provides access to in-app message functionality including retrieving messages, displaying messages, removing messages, and more.

Returns undefined | IterableInAppManager
Example
```
// Get all in-app messages
Iterable.inAppManager.getMessages().then(messages => {
  console.log('Messages:', messages);
});

// Show a specific message
Iterable.inAppManager.showMessage(message, true);
```
- Defined in core/classes/Iterable.ts:80

Methods

`Static`disableDeviceForCurrentUser

disableDeviceForCurrentUser(): void
Disable the device's token for the current user. This will disable push notifications for the current user.

Returns void
Example
```
Iterable.disableDeviceForCurrentUser();
```
- Defined in core/classes/Iterable.ts:316

`Static`getAttributionInfo

getAttributionInfo(): Promise<undefined | IterableAttributionInfo>
Get the stored attribution information -- possibly based on a recent deep link click.

The attribution information contains the campaign ID, template ID, and message ID of the message that prompted the user to recently click a link.

Returns Promise<undefined | IterableAttributionInfo>
See
IterableAttributionInfo
Example
```
 Iterable.getAttributionInfo().then((attributionInfo) => {
   Iterable.updateSubscriptions(
     null,
     [33015, 33016, 33018],
     null,
     null,
     attributionInfo.campaignId,
     attributionInfo.templateId
   );
 });
```
- Defined in core/classes/Iterable.ts:361

`Static`getEmail

getEmail(): Promise<undefined | string>
Get the email associated with the current user.

Returns Promise<undefined | string>
Example
```
Iterable.getEmail().then((email) => {
 // Do something with the email
});
```
- Defined in core/classes/Iterable.ts:237

`Static`getLastPushPayload

getLastPushPayload(): Promise<unknown>
Get the payload of the last push notification with which the user opened the application (by clicking an action button, etc.).

Returns Promise<unknown>
Example
```
Iterable.getLastPushPayload().then((payload) => {
 // Do something with the payload
});
```
- Defined in core/classes/Iterable.ts:333

`Static`getUserId

getUserId(): Promise<undefined | string>
Get the userId associated with the current user.

Returns Promise<undefined | string>
Example
```
Iterable.getUserId().then((userId) => {
 // Do something with the userId
});
```
- Defined in core/classes/Iterable.ts:302

`Static`handleAppLink

handleAppLink(link: string): Promise<boolean>
Handle a universal link.

handleAppLink will hand the passed in URL to IterableConfig.urlHandler, where it is determined whether or not the app can handle the clicked URL.

This can be used to handle deep links, universal links, and other URLs that the app should handle.
Parameters
- link: string
  The tracking URL generated by Iterable for the link you included in your message content.
Returns Promise<boolean>
See
Handling Deep Links in the Iterable React Native SDK

Remarks
When you call Iterable.handleAppLink, you'll pass a URL—the tracking URL generated by Iterable for the link you included in your message content. handleAppLink will fetch the original URL (the one you added to your message) from Iterable and hand it to IterableConfig.urlHandler, where you can analyze it and decide what to do (for example, you might navigate the user to a particular screen in your app that has content related to the link).
Mermaid
The flow goes like this:
%%{init:{"theme":"dark"}}%% graph TD; A[Linking event listener] --> B[Iterable.handleAppLink] --> C[IterableConfig.urlHandler];
%%{init:{"theme":"default"}}%% graph TD; A[Linking event listener] --> B[Iterable.handleAppLink] --> C[IterableConfig.urlHandler];
graph TD; A[Linking event listener] --> B[Iterable.handleAppLink] --> C[IterableConfig.urlHandler];
Example
Basic usage is as follows:
```
 Iterable.handleAppLink('https://www.example.com').then((handled) => {
   console.log('Link handled: ' + handled);
 });
```
For deep linking, your code would look something like this:
```
 import { Linking } from 'react-native';

 const MyApp = () => {
   // To handle deep links clicked when the app is not running,
   // implement `Linking.getInitialURL`:
   Linking.getInitialURL().then((url) => {
     if (url) {
       Iterable.handleAppLink(url);
     }
   });

   // To handle deep links clicked when the app is already open
   // (even if  it's in the background), implement
   // `Linking.addEventListener('url', callback)`
   Linking.addEventListener('url', (event) => {
     if (event.url) {
       Iterable.handleAppLink(event.url);
     }
   });

   // This, in turn, will call your `urlHandler` function on the
   // `IterableConfig` object you used to initialize the SDK.
   const config = new IterableConfig();
   config.urlHandler = (url) => {
     const isCoffeeUrl = url.search(/coffee/i) !== -1;
     if (isCoffeeUrl) {
       // Navigate to the coffee screen
     }
     return isCoffeeUrl;
   };

   return ( /* Your app code here * / );
 }
```
- Defined in core/classes/Iterable.ts:858

`Static`inAppConsume

inAppConsume(
    message: IterableInAppMessage,
    location: IterableInAppLocation,
    source: IterableInAppDeleteSource,
): void
Remove the specified message from the current user's message queue.

This creates an in-app delete event for the specified message on the current user's profile unless otherwise specified (specifying a source of IterableInAppDeleteSource.unknown prevents an inAppDelete event from being created).
Parameters
- message: IterableInAppMessage
  The in-app message (an IterableInAppMessage object)
- location: IterableInAppLocation
  The location of the in-app message (an IterableInAppLocation enum)
- source: IterableInAppDeleteSource
  How the in-app message was deleted (an IterableInAppDeleteSource enum)
Returns void
Example
```
const message = new IterableInAppMessage(
   1234,
   4567,
   IterableInAppTrigger.auto,
   new Date(),
   new Date(),
   false,
   undefined,
   undefined,
   false,
   0,
);

Iterable.inAppConsume(message, IterableInAppLocation.inApp, IterableInAppDeleteSource.delete);
```
Remarks
After a user has read an in-app message, you can consume it so that it's no longer in their queue of messages. When you use the SDK's default rendering for in-app messages, it handles this automatically. However, you can also use this method to do it manually (for example, after rendering an in-app message in a custom way).
- Defined in core/classes/Iterable.ts:673

`Static`initialize

initialize(apiKey: string, config?: IterableConfig): Promise<boolean>
Initializes the Iterable React Native SDK in your app's Javascript or Typescript code.

Pass in a mobile API key distributed with the mobile app. Warning: never user server-side API keys with the React Native SDK, mobile API keys have minimal access for security purposes.

Pass in an IterableConfig object with the various customization properties setup.

WARNING: Never use server-side API keys with Iterable's mobile SDKs. Since API keys are, by necessity, distributed with the mobile apps that contain them, bad actors can potentially access them. For this reason, Iterable provides mobile API keys, which have minimal access.
Parameters
- apiKey: string
  The mobile API key for your application
- config: IterableConfig = ...
  Configuration object for the SDK
Returns Promise<boolean>
Example
Initializing the app could look like this:
```
// Create a new IterableConfig object
const config = new IterableConfig();

// Set various properties on the config object
config.logLevel = IterableLogLevel.debug;

// Initialize the SDK with the API key and config object
Iterable.initialize(API_KEY, config);
```
- Defined in core/classes/Iterable.ts:127

`Static`setAttributionInfo

setAttributionInfo(attributionInfo?: IterableAttributionInfo): void
Manually set the current stored attribution information so that it can later be used when tracking events.

The attribution information contains the campaign ID, template ID, and message ID of the message that prompted the user to recently click a link.
Parameters
- OptionalattributionInfo: IterableAttributionInfo
  Object storing current attribution info
Returns void
See
IterableAttributionInfo

For deep link clicks, Iterable sets attribution information automatically. However, use this method to set it manually if ever necessary.
Example
```
const CAMPAIGN_ID = 1234;
const TEMPLATE_ID = 5678;
const MESSAGE_ID = 9012;

const attributionInfo = new IterableAttributionInfo(CAMPAIGN_ID, TEMPLATE_ID, MESSAGE_ID);

Iterable.setAttributionInfo(attributionInfo);
```
- Defined in core/classes/Iterable.ts:403

`Static`setEmail

setEmail(email?: null | string, authToken?: null | string): void
Associate the current user with the passed in email parameter.

Note: specify a user by calling Iterable.setEmail or Iterable.setUserId, but NOT both
Parameters
- Optionalemail: null | string
  Email address to associate with the current user
- OptionalauthToken: null | string
  Valid, pre-fetched JWT the SDK can use to authenticate API requests, optional - If null/undefined, no JWT related action will be taken
Returns void
Remarks
Iterable's React Native SDK persists the user across app sessions and restarts, until you manually change the user using Iterable.setEmail or Iterable.setUserId.

User profile creation:
If your Iterable project does not have a user with the passed in email, setEmail creates one and adds the email address to the user's Iterable profile.

Registering device token:
If IterableConfig.autoPushRegistration is set to true, calling setEmail automatically registers the device for push notifications and sends the deviceId and token to Iterable.

Optional JWT token parameter:
An optional valid, pre-fetched JWT can be passed in to avoid race conditions. The SDK uses this JWT to authenticate API requests for this user.

Signing out a user from the SDK:
To tell the SDK to sign out the current user, pass null into Iterable.setEmail. If IterableConfig.autoPushRegistration is set to true, calling Iterable.setEmail(null) prevents Iterable from sending further push notifications to that user, for that app, on that device. On the user's Iterable profile, endpointEnabled is set to false for the device.
Example
```
Iterable.setEmail('my.user.name@gmail.com');
```
- Defined in core/classes/Iterable.ts:221

`Static`setUserId

setUserId(userId?: null | string, authToken?: null | string): void
Associate the current user with the passed in userId parameter.

Note: specify a user by calling Iterable.setEmail or Iterable.setUserId, but NOT both.
Parameters
- OptionaluserId: null | string
  User ID to associate with the current user
- OptionalauthToken: null | string
  Valid, pre-fetched JWT the SDK can use to authenticate API requests, optional - If null/undefined, no JWT related action will be taken
Returns void
Remarks
Iterable's React Native SDK persists the user across app sessions and restarts, until you manually change the user using Iterable.setEmail or Iterable.setUserId.

User profile creation:
If your Iterable project does not have a user with the passed in UserId, setUserId creates one and adds a placeholder email address to the user's Iterable profile.

Registering device token:
If IterableConfig.autoPushRegistration is set to true, calling setUserId automatically registers the device for push notifications and sends the deviceId and token to Iterable.

Optional JWT token parameter:
An optional valid, pre-fetched JWT can be passed in to avoid race conditions. The SDK uses this JWT to authenticate API requests for this user.

Signing out a user from the SDK:
To tell the SDK to sign out the current user, pass null into Iterable.setUserId. If IterableConfig.autoPushRegistration is set to true, calling Iterable.setUserId(null) prevents Iterable from sending further push notifications to that user, for that app, on that device. On the user's Iterable profile, endpointEnabled is set to false for the device.
- Defined in core/classes/Iterable.ts:286

`Static`trackEvent

trackEvent(name: string, dataFields?: unknown): void
Create a custom event to the current user's Iterable profile.

Pass in the name of the event stored in eventName key and the data associated with the event. The eventType is set to "customEvent".
Parameters
- name: string
  The event name of the custom event
- OptionaldataFields: unknown
  Descriptive data to store on the custom event
Returns void
Example
```
Iterable.trackEvent("completedOnboarding",
 {
   "includedProfilePhoto": true,
   "favoriteColor": "red",
   "favoriteFlavor": "cinnamon",
 }
);
```
- Defined in core/classes/Iterable.ts:703

`Static`trackInAppClick

trackInAppClick(
    message: IterableInAppMessage,
    location: IterableInAppLocation,
    clickedUrl: string,
): void
Create an inAppClick event for the specified message on the current user's profile for manual tracking purposes. Iterable's SDK automatically tracks in-app message clicks when you use the SDK's default rendering. Click events refer to click events within the in-app message to distinguish from inAppOpen events.
Parameters
- message: IterableInAppMessage
  The in-app message.
- location: IterableInAppLocation
  The location of the in-app message.
- clickedUrl: string
  The URL clicked by the user.
Returns void
Example
```
const message = new IterableInAppMessage(1234, 4567, IterableInAppTrigger.auto, new Date(), new Date(), false, undefined, undefined, false, 0);
Iterable.trackInAppClick(message, IterableInAppLocation.inApp, 'https://www.example.com');
```
Remarks
Iterable's SDK automatically tracks in-app message clicks when you use the SDK's default rendering. However, you can also manually track these events by calling this method.
- Defined in core/classes/Iterable.ts:589

`Static`trackInAppClose

trackInAppClose(
    message: IterableInAppMessage,
    location: IterableInAppLocation,
    source: IterableInAppCloseSource,
    clickedUrl?: string,
): void
Create an inAppClose event for the specified message on the current user's profile for manual tracking purposes. Iterable's SDK automatically tracks in-app message close events when you use the SDK's default rendering.
Parameters
- message: IterableInAppMessage
  The in-app message.
- location: IterableInAppLocation
  The location of the in-app message. Useful for determining if the messages is in a mobile inbox.
- source: IterableInAppCloseSource
  The way the in-app was closed.
- OptionalclickedUrl: string
  The URL clicked by the user.
Returns void
Example
```
const message = new IterableInAppMessage(1234, 4567, IterableInAppTrigger.auto, new Date(), new Date(), false, undefined, undefined, false, 0);
Iterable.trackInAppClose(message, IterableInAppLocation.inApp, IterableInAppCloseSource.back, 'https://www.example.com');
```
Remarks
Iterable's SDK automatically tracks in-app message close events when you use the SDK's default rendering. However, it's also possible to manually track these events by calling this method.
- Defined in core/classes/Iterable.ts:621

`Static`trackInAppOpen

trackInAppOpen(
message: IterableInAppMessage,
location: IterableInAppLocation,
): void
Create an inAppOpen event for the specified message on the current user's profile for manual tracking purposes. Iterable's SDK automatically tracks in-app message opens when you use the SDK's default rendering.
Parameters
- message: IterableInAppMessage
  The in-app message (an IterableInAppMessage object)
- location: IterableInAppLocation
  The location of the in-app message (an IterableInAppLocation enum)
Returns void
Example
```
const message = new IterableInAppMessage(1234, 4567, IterableInAppTrigger.auto, new Date(), new Date(), false, undefined, undefined, false, 0);
Iterable.trackInAppOpen(message, IterableInAppLocation.inApp);
```
Remarks
Iterable's SDK automatically tracks in-app message opens when you use the SDK's default rendering. However, it's also possible to manually track these events by calling this method.
- Defined in core/classes/Iterable.ts:559

`Static`trackPurchase

trackPurchase(
    total: number,
    items: IterableCommerceItem[],
    dataFields?: unknown,
): void
Create a purchase event on the current user's Iterable profile.

Represent each item in the purchase event with an IterableCommerceItem object.
Parameters
- total: number
  The total cost of the purchase
- items: IterableCommerceItem[]
  The items included in the purchase
- OptionaldataFields: unknown
  Descriptive data to store on the purchase event
Returns void
See
IterableCommerceItem

NOTE: total is a parameter that is passed in. Iterable does not sum the price fields of the various items in the purchase event.
Example
```
const items = [
 new IterableCommerceItem('item1', 'Item 1', 10.0, 1),
 new IterableCommerceItem('item2', 'Item 2', 20.0, 2),
];
const dataFields = { 'key1': 'value1', };

Iterable.trackPurchase(30.0, items, dataFields);
```
- Defined in core/classes/Iterable.ts:530

`Static`trackPushOpenWithCampaignId

trackPushOpenWithCampaignId(
    campaignId: number,
    templateId: number,
    messageId: undefined | string,
    appAlreadyRunning: boolean,
    dataFields?: unknown,
): void
Create a pushOpen event on the current user's Iterable profile, populating it with data provided to the method call.

NOTE: Iterable's SDK automatically tracks push notification opens. However, it's also possible to manually track these events by calling this method.
Parameters
- campaignId: number
  The ID of the campaign to associate with the push open
- templateId: number
  The ID of the template to associate with the push open
- messageId: undefined | string
  The ID of the message to associate with the push open
- appAlreadyRunning: boolean
  Whether or not the app was already running when the push notification arrived
- OptionaldataFields: unknown
  Information to store with the push open event
Returns void
Example
```
const CAMPAIGN_ID = 12345;
const TEMPLATE_ID = 67890;
const MESSAGE_ID = '0fc6657517c64014868ea2d15f23082b';
const APP_ALREADY_RUNNING = false;
const DATA_FIELDS = {
   "discount": 0.99,
   "product": "cappuccino",
};

Iterable.trackPushOpen(CAMPAIGN_ID, TEMPLATE_ID, MESSAGE_ID, APP_ALREADY_RUNNING, DATA_FIELDS);
```
- Defined in core/classes/Iterable.ts:438

`Static`updateCart

updateCart(items: IterableCommerceItem[]): void
Update the items saved in the shopping cart (or equivalent).

Represent each item in the updateCart event with an IterableCommerceItem object.
Parameters
- items: IterableCommerceItem[]
  The items added to the shopping cart
Returns void
See
IterableCommerceItem
Example
```
const item = new IterableCommerceItem(
   "TOY1",
   "Red Racecar",
   4.99,
   1,
   "RR123",
   "A small, red racecar.",
   "https://www.example.com/toys/racecar",
   "https://www.example.com/toys/racecar/images/car.png",
   ["Toy", "Inexpensive"],
);

Iterable.updateCart([item]);
```
- Defined in core/classes/Iterable.ts:482

`Static`updateEmail

updateEmail(email: string, authToken?: string): void
Change the value of the email field on the current user's Iterable profile.

If Iterable.setUserId was used to identify the current user, Iterable.updateEmail can be called to give the current user a real (non-placeholder) email address.

An optional valid, pre-fetched JWT can be passed in to avoid race conditions. The SDK uses this JWT to authenticate API requests for this user.
Parameters
- email: string
  The new email to set
- OptionalauthToken: string
  The new auth token (JWT) to set with the new email, optional - If null/undefined, no JWT-related action will be taken
Returns void
Example
```
Iterable.updateEmail('my.new.email@gmail.com', 'myAuthToken');
```
- Defined in core/classes/Iterable.ts:774

`Static`updateSubscriptions

updateSubscriptions(
    emailListIds: undefined | number[],
    unsubscribedChannelIds: undefined | number[],
    unsubscribedMessageTypeIds: undefined | number[],
    subscribedMessageTypeIds: undefined | number[],
    campaignId: number,
    templateId: number,
): void
Update the current user's subscribed email lists, unsubscribed channel IDs, unsubscribed message type IDs (for opt-out message types), and subscribed message type IDs (for opt-in message types) on the current user's profile.

Pass in null for any of emailListIds, unsubscribedChannelIds, unsubscribedMessageTypeIds, or subscribedMessageTypeIds to indicate that Iterable should not change the current value on the current user's profile.
Parameters
- emailListIds: undefined | number[]
  The list of email lists (by ID) to which the user should be subscribed
- unsubscribedChannelIds: undefined | number[]
  The list of message channels (by ID) to which the user should be unsubscribed
- unsubscribedMessageTypeIds: undefined | number[]
  The list of message types (by ID) to which the user should be unsubscribed (for opt-out message types)
- subscribedMessageTypeIds: undefined | number[]
  The list of message types (by ID) to which the user should be subscribed (for opt-in message types)
- campaignId: number
  The campaign ID to associate with events generated by this request, use -1 if unknown or not applicable
- templateId: number
  The template ID to associate with events generated by this request, use -1 if unknown or not applicable
Returns void
Example
```
const emailListIds = [1234, 5678];
const unsubscribedChannelIds = [1234, 5678];
const unsubscribedMessageTypeIds = [1234, 5678];
const subscribedMessageTypeIds = [1234, 5678];
const campaignId = 1234;
const templateId = 5678;

Iterable.updateSubscriptions(
 emailListIds,
 unsubscribedChannelIds,
 unsubscribedMessageTypeIds,
 subscribedMessageTypeIds,
 campaignId,
 templateId,
);
```
- Defined in core/classes/Iterable.ts:898

`Static`updateUser

updateUser(dataFields: unknown, mergeNestedObjects: boolean): void
Save data to the current user's Iterable profile.

If mergeNestedObjects is set to true, top-level objects in the passed in dataFields parameter are merged with their counterparts that already exist on the user's profile. Otherwise, they are added.

If mergeNestedObjects is set to false, the top-level objects in the passed in dataFields parameter overwrite their counterparts that already exist on the user's profile. Otherwise, they are added.
Parameters
- dataFields: unknown
  Data fields to store in user profile
- mergeNestedObjects: boolean
  Whether to merge top-level objects included in dataFields with analogous, existing objects on the user profile (if true) or overwrite them (if false).
Returns void
Example
This call adds the firstName field and favorites object to the current user's Iterable profile. Since mergeNestedObjects is false, this call will overwrite the existing favorites object (if there is one), replacing it with the value in the call (otherwise, it would have merged the two favorites objects).
```
Iterable.updateUser(
  {
    "firstName": "Joe",
    "favorites": {
      "color": "red",
      "flavor": "cinnamon"
    }
  },
  false
);
```
Remarks
IMPORTANT: mergeNestedObjects only works for data that is stored up to one level deep within an object (for example, {mySettings:{mobile:true}}). Note that mergeNestedObjects applies to objects, not arrays.
- Defined in core/classes/Iterable.ts:748

`Static`wakeApp

wakeApp(): void
Launch the application from the background in Android devices.

Android only.

Returns void
Example
```
Iterable.wakeApp();
```
- Defined in core/classes/Iterable.ts:498

Class Iterable

Example

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Returns Iterable

Properties

Staticlogger

StaticsavedConfig

Accessors

StaticinAppManager

Returns undefined | IterableInAppManager

Example

Methods

StaticdisableDeviceForCurrentUser

Returns void

Example

StaticgetAttributionInfo

Returns Promise<undefined | IterableAttributionInfo>

See

Example

StaticgetEmail

Returns Promise<undefined | string>

Example

StaticgetLastPushPayload

Returns Promise<unknown>

Example

StaticgetUserId

Returns Promise<undefined | string>

Example

StatichandleAppLink

Parameters

Returns Promise<boolean>

See

Remarks

Mermaid

The flow goes like this:

Example

StaticinAppConsume

Parameters

Returns void

Example

Remarks

Staticinitialize

Parameters

Returns Promise<boolean>

Example

StaticsetAttributionInfo

Parameters

Returns void

See

Example

StaticsetEmail

Parameters

Returns void

Remarks

User profile creation:

Registering device token:

Optional JWT token parameter:

Signing out a user from the SDK:

Example

StaticsetUserId

Parameters

Returns void

Remarks

User profile creation:

Registering device token:

Optional JWT token parameter:

Signing out a user from the SDK:

StatictrackEvent

Parameters

Returns void

Example

StatictrackInAppClick

Parameters

Returns void

`Static`logger

`Static`savedConfig

`Static`inAppManager

`Static`disableDeviceForCurrentUser

`Static`getAttributionInfo

`Static`getEmail

`Static`getLastPushPayload

`Static`getUserId

`Static`handleAppLink

`Static`inAppConsume

`Static`initialize

`Static`setAttributionInfo

`Static`setEmail

`Static`setUserId

`Static`trackEvent

`Static`trackInAppClick

`Static`trackInAppClose

`Static`trackInAppOpen

`Static`trackPurchase

`Static`trackPushOpenWithCampaignId

`Static`updateCart

`Static`updateEmail

`Static`updateSubscriptions

`Static`updateUser

`Static`wakeApp