Iterable

The Iterable plugin connects your app to Iterable’s iOS and Android SDKs (Overview of Iterable's iOS and Android SDKs) for push delivery, audience targeting, and user identification.

Configure the plugin in the Median dashboard (including API key and optional data region), then use the JavaScript Bridge to initialize the SDK when needed, register for push, request permission, and identify users by email or user ID.

Why use Iterable

• Push delivery: Send Iterable campaigns to devices through the native push channel.
• Segmentation and targeting: Align push with Iterable audiences and campaign logic.
• Flexible initialization: Supply apiKey in App Studio for automatic setup, or call initialize at runtime when you need dynamic configuration.
• User identification: Tie devices to Iterable profiles with setEmail or setUserId, then refresh the push token with registerPush as documented by Iterable.

Prerequisites

• A Median.co app with JavaScript Bridge enabled
• Access to Push Notifications → Iterable in the Median App Dashboard
• An Iterable API key and (if applicable) a data region such as EU
• Deep linking enabled in the app if notification URLs should open in-app

Integration Guide

Plugin setup

Enable the plugin

1. Navigate to Push Notifications: In the Median.co dashboard, open the Push Notifications tab and select Iterable.
2. Enable Iterable: Turn the plugin on and paste your Iterable API key (and data region if required).
3. Configure settings: Adjust active, autoRegister, and related fields to match your rollout. Enable Deep linking in the app so notification links open in-app rather than only in the device browser.

Configuration options

Example configuration:

{
  "active": true | false,
  "autoRegister": true | false, // optional, if true push permission will be requested automatically
  "apiKey": STRING, // if specified initialization will initiate automatically, otherwise provide when initializing at runtime via JavaScript Bridge
  "dataRegion": STRING // if specified (e.g. 'EU') the app will use region-specific endpoints, can also be provided when initializing at runtime via JavaScript Bridge
}

Note: If you omit apiKey from dashboard config, call median.iterable.initialize() from your web layer with the same key and optional dataRegion before relying on other bridge methods.

JavaScript bridge functions

Initialize

Manually initializes the Iterable SDK when you are not relying on automatic initialization from App Studio config.

median.iterable.initialize({
  'apiKey': STRING,
  'dataRegion': STRING, // optional, e.g. 'EU'
  'callback': function // optional otherwise returns promise
});
// Return value:
{
  "success": true | false
}

Parameters:

Check Permission Status

Returns whether the Iterable SDK has been initialized and, when initialized, echoes the active apiKey and dataRegion.

median.iterable.isInitialized({'callback': function});
// Return value:
{
  'initialized': true | false,
  'apiKey': STRING, // available only if initialized is true
  'dataRegion': STRING // available only if initialized is true
}

Parameters:

Register push

Registers the current user for push notifications and refreshes the device token.

median.iterable.registerPush({'callback': function});
// Return value:
{
  "success": true | false
}

Parameters:

Request permission

Prompts the user for push notification permission.

median.iterable.requestPermission({'callback': function});
// Return value:
{
  "granted": true | false
}

Parameters:

Set email

Identifies the current user by email in Iterable. After a successful call, invoke registerPush to generate a new token for that profile.

median.iterable.setEmail({
  'email': STRING,
  'callback': function // optional otherwise returns promise
});
// Return value:
{
  "success": true | false
}

Parameters:

Set user ID

Identifies the current user by user ID. After a successful call, invoke registerPush to generate a new token for that profile.

median.iterable.setUserId({
  'userId': STRING,
  'callback': function
});
// Return value:
{
  "success": true | false
}

Parameters:

Testing checklist

Use this checklist to ensure Iterable is working correctly in your app:

Basic Functionality

• Plugin configuration includes active, valid apiKey, and correct dataRegion when applicable
• median.iterable.isInitialized() reflects the expected state after dashboard config or initialize()
• median.iterable.requestPermission() (or autoRegister) yields the expected permission outcome
• median.iterable.registerPush() completes with success: true after permission is granted

Platform Testing

• Push registration and receipt behave on Android test devices
• Push registration and receipt behave on iOS test devices
• Iterable test sends reach the device after setEmail / setUserId and registerPush

Error Scenarios

• Failed initialize or registerPush paths do not leave the app in a broken state (retry or messaging as needed)
• Behavior is sane when permission is denied (no silent assumptions that push is enabled)

Edge Cases

• Runtime initialize with apiKey / dataRegion matches your Iterable project
• User switching (setEmail / setUserId changes) is followed by registerPush so tokens stay aligned

User Experience

• Permission prompts appear at a sensible time relative to your onboarding
• Deep-linked notification opens land on the correct in-app destination

Troubleshooting