Leanplum allows mobile teams to go from insight to action quickly using the lean cycle of releasing, analyzing, and optimizing content and messaging. See below to learn more about our SDK setup and features.

Setting up the SDK

Follow our setup guides to integrate the Leanplum SDK with your app.

• iOS setup
• Android setup
• Unity setup
• Javascript setup
• React Native setup

Messaging

With Leanplum's messaging features, you can send customized messages to users and analyze your results from the Leanplum dashboard. You can also send messages manually via our API, depending on your organization's needs.

Once you integrate the Leanplum SDK, in-app messaging should be ready to use. Next, set up Push notification registration to send push notifications directly from the Leanplum dashboard. We also offer email services as an add-on feature, so your team can manage all of your app's messaging channels from one place.

Variables

Variables and resources will appear in the Variables tab automatically once they are detected by the SDK. After your variables are defined, you'll be able to change your variable values from the dashboard, without writing additional code or waiting for App Store approval.

You can preview variable changes on your device instantly before you send them out to your users. After you publish your changes, your users will see any updates the next time they open the app. You can also target variable changes to specific user segments to personalize their in-app experience.

After you install the SDK, see Defining variables and Variable types for more.

Analytics

With 19 out-of-the-box metrics, Leanplum's Analytics tab allows you to start gathering intelligence on your app from the moment the SDK is integrated. Our goal is to give you the data and tools you need to create an informed and results-driven content strategy. By seeing which metrics need improvement, you can decide whether to continue with your current strategy or A/B test a new one.

In addition to the metrics calculated automatically by Leanplum, you can also track custom Events and States in your app. Doing so allows you to create custom metrics in the Analytics dashboard. You can also trigger messages and other content changes for your users based on an event or state change.

A/B Testing

Testing different feature releases and messaging strategies ensures that you are rolling out the most effective content for your users. After you set up the Leanplum SDK (along with any custom variables, events, etc.) you'll be able to test different versions of messages or UI changes on a smaller pool of users before releasing changes to your entire userbase.

Once you've collected enough data, Leanplum will notify you of any statistically significant changes in your metrics. Then you can decide which message version or UI change you want to roll out to all of your users.

Initial setup

The steps below use CocoaPods to integrate the Leanplum SDK.

For more detail, you can also check out our generated iOS docs or review the source code on Github.

Download CocoaPods

CocoaPods is the dependency manager for Objective-C and Swift projects. If you haven't already, install CocoaPods by running the following command in the terminal:

$ sudo gem install cocoapods

For issues installing CocoaPods, see their website for help.

Add a Podfile

In the terminal, navigate to your app's directory. Add a Podfile to your app by running the following command:

$ pod init

Edit your Podfile

Open your Podfile by running the following command:

$ open -a Xcode Podfile

Insert the following into your Podfile:

See Geofencing and location for more on setting up location services.

Install your pods

Now, install the Leanplum SDK pods by running the following command:

$ pod install

If you prefer to use Carthage, you can simply add the following to your Cartfile.

Add DEBUG flag (Swift only)

In your Build Settings, add -D DEBUG to Debug mode in Other Swift Flags.

Edit your AppDelegate

Remember to import Leanplum before doing anything. You can avoid this by adding the import to your app's prefix header (.pch) file.

App Version

The App Version in iOS defaults to the main bundle CFBundleVersion.

Verify your setup (iOS)

When testing your build, run your app in Debug/development mode using the Development key. Use the Production key when the app is pushed live (to be used by real users/in production).

The Development key is used to:

• Send data to the development/test pipeline (via an open web socket in real-time)
• Log processes in the debugger for validation
• See and register your developer devices in the dashboard
• Force your test device into specific A/B test variants
• Keep your data segregated from the live users (instead it will show up in the Developer Activity section)
• Update custom templates and variables to the content management system

Run your project and register your device

Registering a test device will allow you to test your messages, variable changes, and other Leanplum projects on a real device.

To register your device, first make sure you're in Debug mode. To ensure Debug mode is enabled, make sure the DEBUG preprocessor macro is set in Build Settings.

Next, go to Devices in the Leanplum dashboard, then hover over your device and click Register.

Test in-app messaging

Send yourself an in-app message to see it in action. While running your device in Debug mode, go to the Leanplum Message Composer. Create a new message and click Send Preview. The message will be sent to all registered test devices.

Create a custom variable (optional)

Variables you define will show up in the Leanplum dashboard, where you can change them, segment them, and A/B test them without having to update your app. You can verify the variable has been set by checking the Variables tab in the Leanplum dashboard.

Add the following lines to your app delegate or another class of your choosing:

See Defining variables for more on setting up variables.

Track an event (optional)

Events allow you to measure statistics about what your users do inside your app. You can verify an event is tracked in the Debugger or Events tabs in the Dashboard.

Add the following lines of code to track an event. You can place it anywhere after calling start; this is just an example:

See Events for more on tracking custom events with Leanplum.

iOS extensions

Leanplum can be used from iOS extensions. Before calling [Leanplum start] when your ViewController loads, you need to call [Leanplum setExtensionContext:self.extensionContext].

The following setup guide is for developers using Gradle to manage dependencies. Supports Android 4.0.1 (API Level 14) and above.

For more detail, feel free to check out our generated Javadoc or view the source code on Github.

Update your Gradle files

Leanplum Android SDK 5.4.2 requires Java 1.8 compiler. Ensure your gradle file uses that version:

In your project-level build.gradle build file:

1. add the Leanplum repo to your allproject repositories. (this is not needed for Android SDK 4.3.0+)
2. add google-services to your dependencies for Firebase Cloud Messaging.

Here's a simple example:

In your module-level build.gradle build file:

1. Add the required Leanplum libraries in your dependencies, based on which Leanplum services you intend to use (see below).

In SDK 4.0+, our features are split into modular libraries.

You can use any combination of these libraries except:

• You do not need to add core with other libraries (if using Gradle). All of our feature-specific libraries automatically include core, so you should only add core if you don’t include any other Leanplum libraries.

Given that, here is a fully-loaded Gradle file.

Or, if you just want core functionality (aka "none of the above"):

You can see more detailed examples in our guide to updating to Android SDK 4.0.

With previous versions of our SDK (< 4.0), you only needed to include com.leanplum:Leanplum. The Leanplum library included FCM and geolocation libraries.

Edit your manifest

On Android SDK 2.1.0+, we support manifest merging with Gradle only which will add all needed services into your manifest automatically, including FCM services.

Here's an example AndroidManifest.xml file:

Edit your application class

Add the following to your application class. You may need to create a new class that extends Application for this step.

If your application class does not extend LeanplumApplication, you must call enableLifecycleCallbacks (like the example below). Failure to do so will prevent the SDK from properly tracking states and displaying in-app messages on app resume.

To use one or more push services alongside Leanplum's push service, you may need to create a custom class that extends the correct Leanplum push messaging class. See our guide here.

Set up push notifications

Below are Firebase Cloud Messaging (FCM) setup instructions. To use this push service with Leanplum, see our guide to using multiple push services.

If you target Android 8.0 (API level 26) or above, you must register at least one notification channel in order to send notifications to users with devices running Android 8.0 (level 26) or later. See our guide to Using Android Notification Channels.

To use FCM with Leanplum, you need to:

1. Verify that your Gradle files include the correct FCM and Leanplum libraries (see above).
2. Download your google-services.json config file (see how here).
3. Add the above file to your root app/ folder.

4. Copy your FCM Server Key. In the Firebase console, click the gear icon next to Overview, then click Project Settings.

Then, in your project's settings, go to the Cloud Messaging tab. In this section of your settings, you will see your Server key. Copy the key.

5. Add your FCM Server Key to Leanplum. In the Leanplum dashboard, in your App Settings click Keys & Settings. Go to the Push Notifications tab and enter/paste your key into the Google API key field.

Add a push notification channel

Once you finish your push setup, you'll need to add a default Android Notification channels for your app using our API. This is required before you can start sending push notifications through Leanplum.

Add Proguard configuration

This is only needed in your proguard-project.txt if you use Proguard to obfuscate your code, and if you install via JAR. Our AAR library already includes this configuration.

-keepclassmembers class *
{
  @com.leanplum.annotations.* <fields>;
}
-keep class com.leanplum.** { *; }
-dontwarn com.leanplum.**

Verify your setup (Android)

For testing purposes, run your app in Debug/development mode using the Development key. The Production key should be used when the app is pushed live and used by real users in production.

The Development key is used to:

• Send data to the development/test pipeline (via an open web socket in real-time)
• Log processes in the debugger for validation
• See and register your developer devices in the dashboard
• Force your test device into specific A/B test variants
• Keep your data segregated from the live users (instead it will show up in the Developer Activity section)
• Update custom templates and variables to the content management system

Run your project and register your device

Registering a test device will allow you to test your messages, variable changes, and other Leanplum projects on a real device.

To register your device, first make sure you're in Debug mode. Then, from the Leanplum dashboard, go to Devices then hover over your device and click Register.

Next, go to Devices in the Leanplum dashboard, then hover over your device and click Register.

Test in-app messaging

Send yourself an in-app message to see it in action. While running your device in Debug mode, go to the Leanplum Message Composer. Create a new message and click Send Preview. The message will be sent to all registered test devices.

Create a custom variable (optional)

Variables you define will show up in the Leanplum dashboard, where you can change them, segment them, and A/B test them without having to update your app. You can verify the variable has been set by checking the Variables tab in the Leanplum dashboard.

Add the following lines to your application class or another class of your choosing:

import com.leanplum.annotations.Variable;
import com.leanplum.annotations.Parser;

public class ApplicationClass extends Application {

  // All variables must be defined before calling Leanplum.start.
  // Use the Parser class (see docs) since your variables are outside of your main activity.
  @Variable public static String welcomeMessage = "Welcome to Leanplum!";

  @Override
  public void onCreate() {
    ...
    // Be sure to set the context to this in the Parser.
    Parser.parseVariables(this);

    // It's important to use the variables changed callback if the value is needed
    // around the time the app starts, so that we're guaranteed to have the latest value.
    Leanplum.addVariablesChangedHandler(new VariablesChangedCallback() {
      @Override
      public void variablesChanged() {
        Log.i("Test", welcomeMessage);
      }
    });
    ...

    Leanplum.start();
  }
}

See Defining variables for more on setting up variables.

Track an event (Optional)

Events allow you to measure statistics about what your users do inside your app. You can also use events to target users for certain messages, tests, or other content changes. You can verify when an event is tracked in the Debugger or the Events tab in the Leanplum dashboard.

Add the following lines of code to track an event. You can place the Leanplum track call anywhere after calling start. For example:

import com.leanplum.annotations.Variable;
import com.leanplum.annotations.Parser;

public class ApplicationClass extends Application {

  @Variable public static String welcomeMessage = "Welcome to Leanplum!";

  @Override
  public void onCreate() {
    ...
    Parser.parseVariables(this);

    Leanplum.addVariablesChangedHandler(new VariablesChangedCallback() {
      @Override
      public void variablesChanged() {
        Log.i("Test", welcomeMessage);
        Leanplum.track("Launch");
      }
    });
    ...

    Leanplum.start();
  }
}

See Events for more on tracking events in Leanplum.

Our Unity SDK includes both a native Unity implementation of the Leanplum SDK as well as wrappers around the native iOS and Android SDKs. This setup allows us to provide feature parity on the iOS and Android platforms while still retaining support for other Unity platforms. The following matrix shows the features supported on each platform:

Install the SDK

Download the latest .unitypackage in the Leanplum Unity SDK.

Supports Unity 5.0 and above for Android, iOS, and Standalone platforms.

Import the UnityPackage into your project

Make sure you import the directories Plugins and Standard Assets. Optionally import Editor, and/or LeanplumSample to include a sample project demonstrating how to manipulate the speed of rain with a Leanplum variable.

Add the Leanplum Prefab

Copy the Leanplum Prefab from Standard Assets/Leanplum into the first scene in your project that loads. Make sure the prefab is linked with the script LeanplumWrapper.cs. This GameObject will persist across scene changes so you don't have to worry about adding it to other scenes.

Add your app keys

Copy your app ID and keys into the Leanplum GameObject's inspector. You can find these in App Settings > Keys & Settings.

Initialize the SDK

The code in LeanplumWrapper.cs initializes the SDK. If you require asset bundle support on iOS and Android, you can switch to use the native Unity implementation for all platforms. However, this means that you won't get in-app messaging or push notification support.

The code snippets below exist only in the LeanplumSDK namespace. Remember to add the following to every source file that calls Leanplum's functions.

using LeanplumSDK;

See below for more on defining variables and tracking events.

Verify the setup

For testing purposes, run your app in Debug/development mode using the Development key. The Production key should be used when the app is pushed live and used by real users in production.

The Development key is used to:

• Send data to the development/test pipeline (via an open web socket in real-time)
• Log processes in the debugger for validation
• See and register your developer devices in the dashboard
• Force your test device into specific A/B test variants
• Keep your data segregated from the live users (instead it will show up in the Developer Activity section)
• Update custom templates and variables to the content management system

Run your project and register your device

Make sure the Development Build checkbox is checked in Unity's Build Settings menu. From the Leanplum dashboard, go to Devices then hover over your device and click Register.

Create a custom variable (optional — Unity)

The variables you define with Leanplum will show up in the Leanplum dashboard, where you can change them, segment them, and A/B test them without having to update your app. You can verify the variable has been set by viewing the Variables tab in Leanplum.

Add the highlighted lines to your app delegate or another class of your choosing:

using LeanplumSDK;

public class LeanplumWrapper : MonoBehaviour
{   ...
    private Var<string> welcomeMessage;

    void Start()
    {   ...
        // Avoid assigning the variable where its declared up top becuase
        // that code may run multiple times and will produce an error.
        welcomeMessage = Var<string>.Define("welcomeMessage", "Welcome to Leanplum!");
        Leanplum.Start();
    }

    void OnEnable()
    {
        // It's important to use the variables changed callback or welcomeMessage.ValueChanged if the
        // value is needed around the time the app starts, so that we're guaranteed to have the latest value.
        Leanplum.VariablesChanged += OnLeanplumOnVariablesChanged;
    }

    void OnDisable()
    {
        Leanplum.VariablesChanged -= OnLeanplumOnVariablesChanged;
    }

    private void OnLeanplumOnVariablesChanged()
    {
        Debug.Log(welcomeMessage.Value);
    }
}

See Defining variables for more on using variables with Leanplum.

Track an event (optional)

Events allow you to measure statistics about what your users do inside your app. You can also trigger messages and other content changes after certain events. You can verify an event is tracked in the Debugger or Events tabs in the Dashboard.

Add the highlighted line of code to track an event. You can place it anywhere after calling start. Example:

using LeanplumSDK;

public class LeanplumWrapper : MonoBehaviour
{   ...
    void Start()
    {   ...
      Leanplum.Track("Launch");
    }
}

See Events for more on tracking events with Leanplum.

Leanplum JavaScript SDK allows you to:

• Collect data from your Web App, Progressive Web App or other JavaScript-based platforms
• Send Push Notifications to Web Browsers
• Send Inbox Messages to Web Apps
• Utilize Variables in Web Apps

Install the SDK

Using NPM

The Leanplum JavaScript SDK is also available as an NPM package. Run npm install leanplum-sdk to install add it in your project.

Using a CDN

You can use the jsdelivr CDN to load the JS SDK:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/leanplum.min.js"></script>

Download

Alternatively, you can download the Leanplum JavaScript SDK (version 1.8.0)

<script type="text/javascript" src="leanplum.js"></script>

Using Web Push messaging

To use web push in your app, you must add the Service Worker file sw.min.js from our SDK to your root directory, then register the Service Worker and user for push notifications.

For more see Push notifications.

Initialize Leanplum

// This value should be set to true only if you're developing on your server.
var isDevelopmentMode = true;

// Sample variables. This can be any JSON object.
var variables = {
 items: {
   color: 'red',
   size: 20,
   showBadges: true
 },
 showAds: true
};

// Get your App ID and Keys from https://www.leanplum.com/dashboard?#/account/apps
if (isDevelopmentMode) {
 Leanplum.setAppIdForDevelopmentMode("YOUR_APP_ID", "YOUR_DEVELOPMENT_KEY");
} else {
 Leanplum.setAppIdForProductionMode("YOUR_APP_ID", "YOUR_PRODUCTION_KEY");
}

Leanplum.setVariables(variables);
Leanplum.start(function(success) {
 console.log('Success: ' + success);
 console.log('Variables', Leanplum.getVariables());
});

Verify the setup

For testing purposes, run your app in Debug/development mode using the Development key. The Production key should be used when the app is pushed live and used by real users in production.

The Development key is used to:

• Send data to the development/test pipeline (via an open web socket in real-time)
• Log processes in the debugger for validation
• See and register your developer devices in the dashboard
• Force your test device into specific A/B test variants
• Keep your data segregated from the live users (instead it will show up in the Developer Activity section)
• Update custom templates and variables to the content management system

Register your device

Be sure to run your app in development mode. From the Leanplum dashboard, go to Devices then hover over your device and click Register.

How to track events in your app

Leanplum.track("View Cart");
Leanplum.track("View Cart", {itemsInCart: 4});
Leanplum.track("Purchase", 4.99, {itemCategory: 'Apparel', itemName: 'Shoes'});

How to track states transitions. These are sections of your app the user is in.

Leanplum.advanceTo("Cart");
Leanplum.advanceTo("Level", level.name);

// The 'null' state. Causes the user to leave the current state and not enter another one.
Leanplum.advanceTo(null);

Passing custom user IDs.

Leanplum.start('mike3958');

Passing user attributes. User attributes are applied to the user, so they're saved across sessions. If an attribute no longer applies, you can set it to null.

Leanplum.start({hasFacebookProfile: true});
Leanplum.start('userId', {age: 20, gender: 'Male'}, callback);

Starts Leanplum by simply loading the cached variables, and doesn't log a new session. Useful for subsequent page loads inside the app.

Leanplum.startFromCache('mike3958');

How to track the session lifecycle.

Leanplum.pauseSession();  // Pauses the current session.
Leanplum.resumeSession();  // Resumes the current session.
Leanplum.stop();  // Ends the current session. Sessions will automatically timeout after 2 hours if stop isn't called explicitly (30 minutes if paused).

Javascript SDK settings

Set the path of the API server.

Leanplum.setApiPath('https://api.leanplum.com/api');

Sets the network timeout in seconds. (Default: 10).

Leanplum.setNetworkTimeout(5);

Sets the request batching strategy. This applies to production mode only. The default behavior is to batch every 5 seconds.

Leanplum.setRequestBatching(false); // No batching.
Leanplum.setRequestBatching(true); // Batching enabled. Unsent requests are sent on start, pauseSession, resumeSession, and stop
Leanplum.setRequestBatching(true, 30); // Same as above except unsent requests are also sent every 30 seconds.

Enables development mode, and sets the app ID and client key.

Leanplum.setAppIdForDevelopmentMode('appId', 'clientKey');

Enables production mode, and sets the app ID and client key.

Leanplum.setAppIdForProductionMode('appId', 'clientKey');

Sets a custom device ID. If this is not called, Leanplum will assign a device ID automatically.

Leanplum.setDeviceId('DevId');

Sets the current version of your app.

Leanplum.setAppVersion('1.0.1');

Sets the device name to override the default.

Leanplum.setDeviceName("Andrew's iMac");

Sets the device model to override the default.

Leanplum.setDeviceModel('Mac');

Sets the system name to override the default.

Leanplum.setSystemName('Mac OS X');

Sets the system version to override the default.

Leanplum.setSystemVersion('10.8');

React Native setup

Using NPM

The Leanplum React Native SDK is available as NPM package. Run npm install @leanplum/react-native-sdk to install add it in your project.

Linking to native dependency

If you are using ReactNative 0.60 or greater, you can take advantage of autolinking.
For Android, gradle will take care of all dependencies.
For iOS only command that needs to be run is:

cd ios && pod install

On older version, linking has to be done manually by executing:

npx react-native link @leanplum/react-native-sdk
and
cd ios && pod install

Additional Android setup

In your generated Android MainApplication.java file add additional code to properly setup Leanplum SDK

Initialize Leanplum

Register your device

Be sure to run your app in development mode. From the Leanplum dashboard, go to Devices then hover over your device and click Register.

How to track events in your app

How to track states transitions. These are sections of your app the user is in.

React Native SDK settings

Enables development mode, and sets the app ID and client key.

Enables production mode, and sets the app ID and client key.

Sets a custom device ID. If this is not called, Leanplum will assign a device ID automatically.

We generally recommend installing the SDK using our dependency managers, but if you'd rather set up your SDK manually, see below for iOS and Android instructions.

• iOS manual setup
• Android manual setup (See note for manual steps.)

You can install our SDK manually using the steps below for iOS.

Install the SDK

First, Download Leanplum's iOS SDK.

Add Leanplum.framework to your project

Drop the .framework package into the "Embedded Binaries" list in your targets > general tab. This will add the .framework to "Linked Frameworks and Libraries" as well.

If you are using the static version of our framework, you only need to add it to "Linked Frameworks and Libraries".

If you want to use Location services on Leanplum, add LeanplumLocation.framework. Alternatively, if you also need iBeacon services on Leanplum, add LeanplumLocationAndBeacons.framework. You can download these from GitHub.

Add Leanplum frameworks to your project

Add CFNetwork, SystemConfiguration, Security, AdSupport, and StoreKit frameworks. AdSupport and StoreKit can be marked as Optional. IDFA is only used (optionally) in development mode and not in the build sent to the App Store. If you're linking LeanplumLocation or LeanplumLocationAndBeacons, add CoreLocation.

Add the -ObjC -fobjc-arc linker flags (optional)

This is only needed if your project has CLANG_ENABLE_OBJC_ARC or Objective-C Automatic Reference Counting set to NO (aka ARC disabled). By default ARC is enabled, so this flag is only needed if you have disabled ARC.

The -ObjC flag may not be compatible with certain libraries. You can replace it with -force_load ${SRCROOT}/Leanplum.framework/Leanplum. Make sure the path matches the location of Leanplum.framework on your filesystem.

Strip framework script (for release builds)

In order to submit a release build of the app to the App Store, you must make sure that the following script is in place to strip the framework to valid architectures. Navigate to 'Build Phases' in your project, add 'New Run Script', and move the 'New Run Script' after the Embed Frameworks. Then add the following code:

cd "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Leanplum.framework/"
lipo -remove i386 -remove x86_64 Leanplum -output Leanplum

Make sure to check 'Run script only when installing'. Once completed, the setup should look like the following:

Add DEBUG flag (optional)

Add -D DEBUG to Other Swift Flags only for Debug mode.

Edit your AppDelegate

Remember to import Leanplum before doing anything. You can avoid this by adding the import to your app's prefix header (.pch) file.

For tighter security, remove your development key from your app delegate before submitting to the App Store.

Verify the setup

Verify the setup

When testing your build, run your app in Debug/development mode using the Development key. Use the Production key when the app is pushed live (to be used by real users/in production).

The Development key is used to:

• Send data to the development/test pipeline (via an open web socket in real-time)
• Log processes in the debugger for validation
• See and register your developer devices in the dashboard
• Force your test device into specific A/B test variants
• Keep your data segregated from the live users (instead it will show up in the Developer Activity section)
• Update custom templates and variables to the content management system

Run your project and register your device

Make sure you're in Debug mode. To ensure Debug mode is enabled, make sure the DEBUG preprocessor macro is set in Build Settings.

From the Leanplum dashboard, go to Devices then hover over your device and click Register.

Test in-app messaging

Send yourself an in-app message to see it in action. While running your device in Debug mode, go to the Leanplum Message Composer. Create a new message and click Send Preview. The message will be sent to all registered test devices.

Create a custom variable (optional)

The variables you define will show up in the Leanplum dashboard, where you can change them, segment them, and A/B test them without having to update your app. You can verify the variable has been set by viewing the Variables tab in the Leanplum dashboard.

Add the following lines to your app delegate or another class of your choosing:

For more on Variables, see Defining variables.

Track an event (optional)

Events allow you to measure statistics about what your users do in your app. You can also use events to trigger messages and other content changes. You can verify an event is tracked in the Debugger or Events tabs in the Leanplum dashboard.

Add the following lines of code to track an event. You can place it anywhere after calling start. Example:

For more on tracking events with Leanplum, see Events.

For a manual setup, follow the steps in our Android SDK setup until you get to the Edit your manifest step.

Next, download our SDK. Be sure to drag the .jar file for each required library into your project's libs/ folder. Also include leanplum-core (and leanplum-push if using either push library).

See the .jar manifest file below for more info:

You can create variables that can take on new values from the server. Using variables in the Leanplum dashboard allows you to roll out changes without having to push an update through the App Store or Google Play. You can also create A/B tests to change variables for only a percentage of your users.

Variable data comes back asynchronously after you call start. If you need to use a variable when the app starts, make sure you use Callbacks.

When you define a variable in your code, it will appear in the Variables tab in Leanplum the next time your app starts in development mode.

iOS

It's important to define all of your variables before calling Leanplum.Start. Use periods to group variables on the dashboard.

Objective-C

Define variables outside of your methods, like you would a constant, using our DEFINE_VAR macros. Use underscores in the name to group values into a structured variable. See Modeling structured data for examples.

Swift

Swift doesn't support macros like Objective-C. Instead, define variables using the Var class directly. Use dots in the name to group values into a structured variable. See Modeling structured data for examples.

With Swift, you must define all of your Leanplum variables before calling Leanplum.start.

To access a variable in another controller or file, call define again; the first define call (before start) will set the value, subsequent calls will return the cached value. Be careful where you place define calls to ensure the first call is truly called first.

See Variable types for more specifics on each type of variable.

Android (Java)

There are two ways to define variables.

1. Using the @Variable annotation on public static class members
   This is the easiest and most convenient way to define variables.

You can use this method to define variables:

• Inside your Application class if it extends LeanplumApplication.
• In your main activity if it extends one of the LeanplumActivityclasses and calls Leanplum.start.
• In another class. Use the Parser class to detect the annotations before calling Leanplum.start.

If you choose to define variables in an Activity or Class that does make your start call, you will need to use Parser.parseVariablesForClasses to collect these variable definitions before your start call.

For example, if we have variables defined in ClassA and ClassB, we need to add the following to our ApplicationClass before start:

If you define your variables in an ApplicationClass or Activity where you call start, and the class does not extend LeanplumApplication or LeanplumActivity, then you must use the Parser class to detect that class's variable annotations.

2. Using Var.define

You must define variables with this method before calling Leanplum.start.

Unity

It's important to define all of your variables before calling Leanplum.Start. Use periods to group variables on the dashboard.

JavaScript (HTML5)

Sets your variables:

Gets your variables:

To resolve a file variable filename to a path, call the getFileUrl method, available in SDK versions 1.7.0 and later.

React Native

Variables need to be set before calling start method.

Set asset:

Get variables will return all variables that were set by setVariables() before calling start method.

Get variable with name will return only variable that was set by setVariables() before calling start method.

Get asset:

Float

Boolean

String

Color

Assets

File variables work like variables except that the file data comes back from Leanplum separately. When you edit a file variable, you change its filename. If a file with the same name does not exist on the device, it will download from Leanplum.

Dictionary

Array (List)

Say you have a bunch of items in your app, and each item has properties. Leanplum gives you the flexibility to model one property of the object at a time, one object at a time, or the entire structure at once, depending on how you'd like to set up your code.

For example, if you want to create a structure like this:

You could model each individual field like so:

Or you could model each object:

Or the entire structure:

All of the above declarations will show up identically on our dashboard. Leanplum understands to group variables that use underscores (ObjC) or dots (Swift) in their names. The last method is convenient because instead of specifying the JSON data in code, you could potentially load it from a file and then convert it to a dictionary.

When the variable values are ready, you can get different slices of the variables using objectForKey[Path].

Using objectForKey:

Because Leanplum variables and resources are retrieved from the server asynchronously after start, you need to wait for the values to be downloaded before using them in your code. The proper way to do this is to use one of the callbacks provided by our SDK.

The SDK will use locally-cached values, if available, and changes will only be synced on start or forceContentUpdate.

You can use callbacks multiple times across different classes in your app. However, where you place the callback may influence when it is executed. If you call one after the necessary variables (and/or files) for that callback have been synced, the code in the callback will just execute again immediately.

Timing

All callbacks are executed on start, regardless of whether the file(s) or variable(s) have changed. The distinction between our callbacks is their behavior on forceContentUpdate — namely, which files or variables will trigger the callback. You can watch a single variable, a single file, all variables, or all variables and all files.

After Leanplum start

This callback is executed only when the start call finishes and all variables and files are returned from the Leanplum server. It will not be executed on forceContentUpdate.

You can use this callback with a splash screen to wait and then load a new view after start finishes, so you don't have to worry about checking when your variables have their values.

When a variable is ready

This callback is executed after start every time, but only after forceContentUpdate if a specific variable has changed (not supported on JavaScript).

When all variables are ready

This callback is executed after start every time, but only after forceContentUpdate if any variable has changed.

You can use forceContentUpdate (except in JavaScript) to re-sync with Leanplum during an active session.

When a file is ready

This callback will execute after start every time, but only after forceContentUpdate when the file has changed. If the file is unchanged, no download will occur and the callback will not be executed.

When all variables and files are ready

You can also wait for all variable changes and file downloads. This callback will execute after start, but only after forceContentUpdate if any of your Leanplum variables or files have changed.

Testing callbacks in development mode

When you're testing your app, it's often useful to tweak values and see the result instantly. If you use Variable callbacks, your variables will change immediately after you change them in the Leanplum dashboard.

If you want to mimic your users' experience and don't want to see real-time changes when testing, use the start callback, which is only triggered the first time variables receive their values on start.

Leanplum will tell you if it couldn't connect to the server, in which case the values will be whatever they were the last time the app was run (or their default values set in the code if the app hasn't been run yet).

Leanplum’s SDK is designed to sync variables, user attributes, messages, and A/B tests on Leanplum.start, at the beginning of a new session. This ensures users receive the latest updates and messages, and that they are entered into latest A/B tests.

By default, we do not sync these values in the middle of a user’s session (after the initial call to start). Our SDK was designed this way to keep it as efficient as possible, requiring only one call to Leanplum’s servers for an entire session, and to keep your app as stable as possible by not altering the app as your users use it.

For most cases, syncing on start is the easiest and best way to keep variables, message targeting and A/B test segments up-to-date.

Using forceContentUpdate

However, there may be some cases where you want to update your messaging or A/B tests mid-session, to be sure a user is appropriately targeted and/or included in a test.

Some examples might be:

• when a user comes back from backgrounding the app (and something may have changed server-side)
• when a user levels up in a game (State or Event change)
• when a user goes from a silver member to gold (User Attribute change)

For these cases, you can force a content update by calling Leanplum.forceContentUpdate(), which syncs variables, user attributes, messages, and A/B tests. Any callbacks you have set up, like onVariablesChanged, will be invoked again automatically.

Events allow you to track user activity in your app. You can also use events to target users for certain messages, tests, or other content changes. You can verify when an event is tracked in the Debugger or the Events tab in the Leanplum dashboard.

An event is anything that can occur in your app. Events include clicking on a link, sharing, purchasing, killing enemies, etc. All events are timestamped according to when they occur. Thus, it is not advisable to log too many events, as each one will have to be sent to our server.

A parameter is a piece of data associated with an event or state. You can supply parameters as a dictionary along with events and states. Here are some reports you can run with parameters:

• Filter reports by event parameter values
• Group metrics by distinct event parameter values (creates a bar graph + table). Example: Show me my top purchased items.
• Group metrics by ranges of event parameter values (creates a histogram + table). Example: Show me the distribution of purchase prices. Example: Show me the distribution of points scored.
• Create custom metrics for numeric parameter values, like totals and averages. Example: For a purchase event, track the average revenue and the amount of currency bought per user.

Events and states accumulate over time, and we send events in batches periodically to minimize network usage and maximize battery life.

Tracking an event

Add the following lines of code to track an event. You can place the Leanplum track call anywhere as long as it executes after start (examples below):

Here are some more examples:

Tracking purchase and monetization events

You can track purchases or other monetization events in Leanplum, which will provide you with revenue metrics in your Analytics reports.

In-app purchases (iOS)

Leanplum supports receipt validation with the App Store and Google Play. On iOS, you can track in-app purchases automatically. Simply add this line of code before Leanplum starts:

Leanplum will also convert all purchases to USD. To require valid receipts upon purchase or change your preferred currency, update your preferences in App settings in the dashboard.

Android in-app purchases

If your app uses Google Play In-App Billing, Leanplum can automatically track those purchases and validate receipts with the Google Play store. First, provide us with your Google Play license key. Next, add the following code sample in your class that implements ``com.android.vending.billing.util.IabHelper.OnIabPurchaseFinishedListener:

Manually tracking monetization events

You can manually track your monetization event within the app. To do so you have to pass a purchase event name, a purchase value, the currency code, and parameters with info about the purchase event with each purchase (all the parameters are required).

The purchase event name is defined by default as “Purchase”. Based on the currency code being passed, the value will be converted to USD automatically in the Dashboard.

Other monetization events

You can also use the standard event tracking for monetization events as well. It works like any other event — just use "Purchase" as the event name and a value.

The only difference is that unlike using trackPurchase, the normal Leanplum.track call will not automatically convert different currencies to USD.

The value should be the revenue for the transaction in a common currency.

If you prefer to use a different event name than "Purchase", you can choose a different name. Select the + tile on the Analytics page for a new metric. In the dialogue box that opens, select the Monetization category and edit the purchase event. The changes will be applied retroactively.

A state is any part of your app a user can be in. For example, some states can include being in a particular level, watching a video, or browsing an in-app store.

All states have a time and a duration. The duration is set automatically — when one state begins, the previous one ends.

Advancing to a state

This example is called when the user advances to the next level.

Pausing and resuming

This is useful if your game has a "pause" mode. You shouldn't call it when someone switches out of your app because that's done automatically.

The nil / null state

This state causes the user to leave the current state and not enter another one.

When Leanplum starts for the first time in your app, it creates a new user profile or User ID. Unless you set up your own concept of User IDs, the UserID value will be identical to the DeviceID value, and Leanplum will start tracking sessions for this user.

Sessions are how Leanplum organizes each user's events, states, and other general activity.

See below for more on handling user IDs, devices, and sessions.

The device ID uniquely identifies the devices and is determined automatically by the SDK. See below for details on iOS and Android device IDs.

iOS device ID

On iOS, by default, we use the identifierForVendor. If the device is pre-iOS 6, we use a hash of the MAC address, and in development mode, we use the advertising identifier.

You can choose how the device ID is set the first time start is called on that device by calling one of these before start:

• LEANPLUM_USE_ADVERTISING_ID: a macro that uses the advertising identifier.
• [Leanplum setDeviceId:@"customAndUniqueId"]: Sets the device ID to a custom ID. Make sure that your custom ID is unique per device.

Android device ID

On Android, by default, we use an MD5 hash of the MAC address if the user is on a version prior to Marshmallow (Android 6) and if your app has ACCESS_WIFI_STATE permissions. Otherwise, we use the ANDROID_ID.

You can choose how the device ID will be set the first time start is called on that device by calling one of these before start:

• Leanplum.setDeviceIdMode(LeanplumDeviceIdMode.ANDROID_ID) Uses the ANDROID_ID.
• Leanplum.setDeviceIdMode(LeanplumDeviceIdMode.ADVERTISING_ID) Uses advertising ID if available; otherwise, uses the MD5 hash of the MAC address if the user is on a version prior to Marshmallow (Android 6) and your app has ACCESS_WIFI_STATE permissions. Otherwise, we use the ANDROID_ID.
• Leanplum.setDeviceId("customAndUniqueId") Sets the device ID to a custom ID. Make sure that your custom ID is unique per device.

Whether or not you set a DeviceIdMode, the SDK uses the following logic to set the deviceId (unless you use setDeviceId):

1. If DeviceIdMode is set to ADVERTISING_ID, use ADVERTISING_ID if available. Otherwise, continue.
2. If DeviceIdMode is set to ANDROID_ID, use ANDROID_ID if available. Otherwise, continue.
3. If a MAC address is available (Android < 6.0 and ACCESS_WIFI_STATE permission), use a hash of the MAC address. Otherwise, continue.
4. If ANDROID_ID is available, use ANDROID_ID. Otherwise, continue.
5. Otherwise, use a randomly generated device ID.

You can view the source code here.

Unity device ID

The device ID uniquely identifies the devices and is determined automatically by the SDK. On Unity, we use SystemInfo.deviceUniqueIdentifier to get the device ID. Refer to the Unity documentation to learn more.

JavaScript (HTML5) device ID

The device ID uniquely identifies the devices and is determined automatically by the SDK. In the JavaScript SDK, we generate a unique device ID from a random selection of numbers and letters totaling 16 characters. We take that device ID and persist it using localStorage. You can set a custom device ID instead using Leanplum.setDeviceId.

React Native device ID

The device ID uniquely identifies the devices and is determined automatically by the SDK. In the React Native SDK, we use the platform-specific logic for iOS or Android as covered in detail above. We take that device ID and persist it using AsyncStorage. You can set a custom device ID instead using Leanplum.setDeviceId.

When Leanplum start is called for the first time on a device, a new user profile is created and Leanplum starts tracking activity and sessions for this user. If no custom User ID is sent with the start call, the User ID value is set to the Device ID.

If you have your own concept of User IDs, you can pass a User ID in the start call. This way, if the user has multiple devices, we will count them as the same user and merge their profiles.

In some cases, you can also set the User ID after start. See more below:

Logins

Passing a user ID with start may not work well if you have a login system. You should still call start early on to track user activity, then set the user ID later on with setUserId when the user logs in.

When the user ID is set for the first time on a device, the existing profile in Leanplum is updated with that user ID and all previously tracked data remains.

After the first setUserId call, each subsequent call that includes a different ID will end the current User session, and create a new session for the new User. If the new User ID doesn't exist, a new User Profile will be created in Leanplum.

Here's how setting the user ID with setUserId works with typical registration and login scenarios:

• Register: If a user ID has not been set on this device yet and the supplied user ID does not exist, Leanplum will update the current user profile (created on start) with the supplied user ID (replacing the device ID).
• Login: If a user ID has not been set on this device yet and the supplied user ID does exist, the current and existing user profiles will be merged. This ensures that users with multiple devices are tracked as one user. If the same user logs back in on this device, no changes will be made to their profile since their user ID is already set.
• Switch user: If a user ID has been set on this device and the supplied user ID is different, the current session will be ended and a new session will be started for the supplied user ID. A user with the supplied user ID will be created if one does not already exist.

Logouts

Leanplum will not end the session after a user logs out and does not include any methods to do so. All user activity is tracked and attributed to the last logged-in user (set by the setUserId call). This allows you to track activity in your app even while the user is logged out.

If you want to keep track of which users are logged in and which are logged out, set a user attribute (e.g. logged_in).

A user attribute is any piece of data associated with a user that you provide to the SDK. Each session has its own user attributes, but they get copied from one session to the next. This is in contrast to event parameters, which may take on different values per event. For this reason, you generally use user attributes for things that do not change much within the session, or with which you want the entire session associated.

Uses:

• Personalizing content (variables, messages, resources, and interfaces) to different types of users.
• Targeting an A/B test.
• Filtering reports by a particular user attribute, like only looking at data for "whales".
• Grouping reports (constructing a bar graph or histogram), by different attribute values. E.g. Create a histogram of average session length by number of friends.

Examples:

• Gender
• Age
• Number of friends
• User interests
• Email (required for running email campaigns)

Constraints:

• Up to 200 attributes can be defined for your app.
• Attribute names must be strings, and values must be strings or numbers.
• Attribute values will be the same across all events and states in a particular session.