React Native

React Native version

We recommend you use the latest stable version of React Native, defined in package.json. The Localytics SDK was last verified against version 0.71.4.

"dependencies": {
  ...
  "react-native": "0.71.4",
  ...
}

Install npm module

$ cd YourProjectDirectory
$ npm install
For users who support RN 0.60 and above use the following with androidX support:
$ npm install -S localytics-react-native
For users who support RN 0.59 and below use the following:
$ npm install -S localytics-react-native-legacy

1. Manual Linking the SDK as a dependency (Skip this if you are using Autolinking):

   $ cd YourProjectDirectory
   For users who support RN 0.60 and above use the following with androidX support:
   $ react-native link localytics-react-native
   For users who support RN 0.59 and below use the following:
   $ react-native link localytics-react-native-legacy
   

2. Ensure the iOS cocoapod is installed:

   $ cd iOS
   $ pod install
   

3. Update your project’s top-level build.gradle script to include the Localytics Maven repository.

   allprojects {
       repositories {
           ...
           google()
           jcenter()
           maven { url 'https://maven.localytics.com/public' }
           ...
       }
   }
   

That's it! You're all set to begin integrating Localytics in your project.

1. Configure Test mode

To configure test mode, you'll need to setup a URL scheme. The URL scheme is defined as "amp" followed by your Localytics app key, as demonstrated below. You can find your app key in the Localytics Dashboard. If you switch between multiple Localytics app keys, as when you have separate testing and production app keys, there's no harm in registering both URL schemes.

1. Enter Project Navigator view and click on your project icon. It should be at the top of the Project Navigator.
2. Select your target from the sidebar or from the dropdown menu, then select the Info tab.
3. Open the URL Types expander and click +.
4. In the URL Schemes field, enter "amp" followed by your Localytics app key.

2. Initialize the SDK

In order to run the Localytics SDK, you must initialize the SDK using your Localytics app key. You can find your app key in the Localytics Dashboard.

In your AppDelegate.mm:

1. Import the Localytics SDK under any existing imports.

   Objective-C Swift

   #import <Localytics/Localytics.h>
   

   import Localytics
   

2. Add the following line to the start of didFinishLaunchingWithOptions:.

   Objective-C Swift

   [Localytics autoIntegrate:@"YOUR-LOCALYTICS-APP-KEY"
       withLocalyticsOptions:@{
                               LOCALYTICS_WIFI_UPLOAD_INTERVAL_SECONDS: @5,
                               LOCALYTICS_GREAT_NETWORK_UPLOAD_INTERVAL_SECONDS: @10,
                               LOCALYTICS_DECENT_NETWORK_UPLOAD_INTERVAL_SECONDS: @30,
                               LOCALYTICS_BAD_NETWORK_UPLOAD_INTERVAL_SECONDS: @90
                             }
               launchOptions:launchOptions];
   

   Localytics.autoIntegrate("YOUR-LOCALYTICS-APP-KEY", withLocalyticsOptions:[
                           LOCALYTICS_WIFI_UPLOAD_INTERVAL_SECONDS: 5,
                           LOCALYTICS_GREAT_NETWORK_UPLOAD_INTERVAL_SECONDS: 10,
                           LOCALYTICS_DECENT_NETWORK_UPLOAD_INTERVAL_SECONDS: 30,
                           LOCALYTICS_BAD_NETWORK_UPLOAD_INTERVAL_SECONDS: 90
                         ], launchOptions: launchOptions)
   

   Localytics attempts to upload user data quickly to our backend to power time sensitive messaging use cases. By default, Localytics will upload data periodically based on the state of a user's network connection. However, you have full flexibility over this behavior. While not recommended, you can change the upload intervals for each type of connection, and even remove this type of behavior entirely and depend on your own Localytics.upload() calls to upload data whenever you wish.

   To use the default intervals provided by Localytics, you can pass in nil into localyticsOptions. If you would like to disable scheduled uploads, pass in -1 as the value for all keys.

   The available keys for setting upload intervals are:

   • LOCALYTICS_WIFI_UPLOAD_INTERVAL_SECONDS: Defines the interval that will be used in the case of a WiFi connection. Having a WiFi connection will supersede any mobile data connection. Default value is 5 seconds.
   • LOCALYTICS_GREAT_NETWORK_UPLOAD_INTERVAL_SECONDS: Defines the interval that will be used in the case of 4G or LTE connections. Default value is 10 seconds.
   • LOCALYTICS_DECENT_NETWORK_UPLOAD_INTERVAL_SECONDS: Defines the interval that will be used in the case of 3G connection. Default value is 30 seconds.
   • LOCALYTICS_BAD_NETWORK_UPLOAD_INTERVAL_SECONDS: Defines the interval that will be used in the case of 2G or EDGE connections. Default value is 90 seconds.

3. Compile and run your app.

1. Configure Test Mode

<intent-filter>
  <data android:scheme="ampYOUR-LOCALYTICS-APP-KEY" />
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
</intent-filter>

2. Add localytics.xml resource file

In order to run the Localytics SDK, you must initialize the SDK using your Localytics app key. You can find your app key in the Localytics Dashboard.

SDK 5.0 takes advantage of manifest merging in Android. This will help you quickly set up Localytics in your project by automatically including receivers and services in your Android Manifest.

To use manifest merging, the Localytics SDK relies on the presence of a localytics.xml file in the main/res/values directory of your project. You can download a sample localytics.xml file here.

Additionally, should you need to change any values, you can take a look at the full list of possible keys and how they are used.

3. Modify the MainActivity.java

Add the following imports.

import android.content.Intent;
import com.localytics.androidx.Localytics;

Add the following to the onNewIntent method.

@Override
public void onNewIntent(Intent intent) {
  super.onNewIntent(intent);

  Localytics.onNewIntent(this, intent);
}

4. Modify the MainApplication.java

Add the following import:

import com.localytics.androidx.Localytics;

Add the following to the onCreate method.

@Override
public void onCreate() {
  super.onCreate();
  SoLoader.init(this, /* native exopackage */ false);

  Localytics.autoIntegrate(this);
}

Purchased

LLLocalytics.tagPurchased({'itemName': 'Shirt', 'itemId': 'sku-123', 'itemType': 'Apparel', 'itemPrice': 15, 'attributes': {'extraAttributeKey': 'extraAttributeValue'}});

Added to Cart

LLLocalytics.tagAddedToCart({'itemName': 'Shirt', 'itemId': 'sku-123', 'itemType': 'Apparel', 'itemPrice': 15, 'attributes': {'extraAttributeKey': 'extraAttributeValue'}});

Started Checkout

LLLocalytics.tagStartedCheckout({'itemCount': 50, 'totalPrice': 2, 'attributes': {'extraAttributeKey': 'extraAttributeValue'}});

Completed Checkout

LLLocalytics.tagCompletedCheckout({'itemCount': 50, 'totalPrice': 2, 'attributes': {'extraAttributeKey': 'extraAttributeValue'}});

Content Viewed

LLLocalytics.tagContentViewed({'contentName': 'Top 10', 'contentId': 'e8z7319zbe', 'contentType': 'Article', 'attributes': {'extraAttributeKey': 'extraAttributeValue'}});

Searched

LLLocalytics.tagSearched({'queryText': 'Celtics', 'contentType': 'Sports', 'resultCount': 15, 'attributes': {'extraAttributeKey': 'extraAttributeValue'}});

Shared

LLLocalytics.tagShared({'contentName': 'Top 10', 'contentId': 'e8z7319zbe', 'contentType': Article, 'methodName': 'Twitter', attributes': {'extraAttributeKey': 'extraAttributeValue'}});

Content Rated

LLLocalytics.tagContentViewed({'contentName': 'Headlines', 'contentId': '8a4z5j9q', 'contentType': 'Song', 'Rating': 5, 'attributes': {'extraAttributeKey': 'extraAttributeValue'}});

Customer Registered

The customer parameter is optional - you can pass in null. However, if you do choose to include an customer object, the appropriate identifying users properties will be automatically set.

var customer = {'customerId': '3neRKTxbNWYKM4NJ',
                 'firstName': 'John',
                  'lastName': 'Smith',
                  'fullName': 'Sir John Smith, III',
              'emailAddress': 'sir.john@smith.com'};

LLLocalytics.tagCustomerRegistered({'customer': customer, 'methodName': 'Facebook', 'attributes': {'extraAttributeKey': 'extraAttributeValue'}});

Customer Logged In

The customer parameter is optional - you can pass in null. However, if you do choose to include an customer object, the appropriate identifying users properties will be automatically set.

var customer = {'customerId': '3neRKTxbNWYKM4NJ',
                 'firstName': 'John',
                  'lastName': 'Smith',
                  'fullName': 'Sir John Smith, III',
              'emailAddress': 'sir.john@smith.com'};

LLLocalytics.tagCustomerLoggedIn({'customer': customer, 'methodName': 'Facebook', 'attributes': {'extraAttributeKey': 'extraAttributeValue'}});

Customer Logged Out

LLLocalytics.tagLoggedOut({'extraAttributeKey': 'extraAttributeValue'});

Invited

LLLocalytics.tagInvited({'methodName': 'SMS', 'attributes': {'extraAttributeKey': 'extraAttributeValue'}});

Numeric value

LLLocalytics.setProfileAttribute({'name': 'Age', 'value': 45, 'scope': 'org'});
			

Numeric values in a set

LLLocalytics.setProfileAttribute({'name': 'Lucky numbers', 'value': [8, 13], 'scope': 'app'});
			

Date value

LLLocalytics.setProfileAttribute({'name': 'Birthday', 'value': '1962-11-23', 'scope': 'org'});
			

Date values in a set

LLLocalytics.setProfileAttribute({'name': 'Upcoming Milestone Dates', 'value': ['2015-10-01', '2016-03-17'], 'scope': 'app'});
			

String value

LLLocalytics.setProfileAttribute({'name': 'Hometown', 'value': 'New York, New York', 'scope': 'org'});
			

String values in a set

LLLocalytics.setProfileAttribute({'name': 'States Visited', 'value': ['New York', 'California', 'South Dakota'], 'scope': 'app'});
			

Adding a numeric value to a set

LLLocalytics.addProfileAttributesToSet({'name': 'Lucky numbers', 'values': [7, 21], 'scope': 'app'});
			

Adding a date value to a set

LLLocalytics.addProfileAttributesToSet({'name': 'Upcoming Milestone Dates', 'values': ['2015-04-19', '2015-12-24'], 'scope': 'app'});
			

Adding a string value to a set

LLLocalytics.addProfileAttributesToSet({'name': 'States Visited', 'values': ['North Dakota'], 'scope': 'app'});
			

Removing numeric values from a set

LLLocalytics.removeProfileAttributesFromSet({'name': 'Lucky numbers', 'values': [8, 9], 'scope': 'app'});
			

Removing date values from a set

LLLocalytics.removeProfileAttributesFromSet({'name': 'Upcoming Milestone Dates', 'values': ['2016-03-17'], 'scope': 'app'});
			

Removing string values from a set

LLLocalytics.removeProfileAttributesFromSet({'name': 'States Visited', 'values': ['California'], 'scope': 'app'});
			

Instrumenting marketing triggers

Instrumenting Marketing Triggers in the app’s code base is simple. It’s essentially the same as tagging an Event, but rather than using LLLocalytics.tagEvent() you will use the following:

LLLocalytics.triggerInAppMessage({'triggerName': 'Item Purchased'});

Marketing triggers with attributes

To create a trigger with additional attribute conditions, use:

LLLocalytics.triggerInAppMessage({'triggerName': 'Item Purchased', 'attributes': {'Item Name': 'Stickers'}});

Because there’s no data about that trigger in the Localytics backend, you’ll need to manually send the trigger attribute mappings to Localytics via a reported Event instead, at least one time. Essentially, you must fire an actual Event that reaches Localytics server once. You can do this by:

For one session tied to your app key - for example, just in your dev build but tagged with your production key temporarily - switch that triggerInAppMessage call to a standard tagEvent call instead, and run the app through that code to actually send the event to Localytics.

This will populate the event name and attributes in the autocomplete dialog within 10 minutes. Then you can switch the tag back from tagEvent to triggerInAppMessage. From there, you will be able to target on the trigger & attributes as if it were a normal event in the dashboard.

Selecting marketing triggers in the dashboard

Once the marketing trigger has been instrumented in the app’s code base, you can use these to trigger in-app messages in the Localytics dashboard. When you get to the Scheduling page of the campaign setup process, you will chose the “Event” trigger. For these marketing triggers, you will need to type in the name of the marketing trigger in the drop down (as seen below) - it will not automatically populate as the dashboard events do.

Dismiss button location

To globally set the dismiss button location to the left, use:

LLLocalytics.setInAppMessageDismissButtonLocation('left');

To globally set the dismiss button location to the right, use:

LLLocalytics.setInAppMessageDismissButtonLocation('right');

LLLocalytics.setInAppMessageDismissButtonHidden(true);

Customize In-App properties

LLLocalytics.setInAppMessageConfiguration({});

• aspectRatio - The value passed in should be a float value representing a ratio of height to width. This property is only relevant for center in-app creatives.
• bannerOffsetDps - The value passed in should always be a positive density independent pixel offset from the top or bottom of the screen. This property is only relevant for top and bottom banner in-app creatives.
• backgroundAlpha - The value passed in should be a float value between 0.0 (transparent) and 1.0 (opaque).
• dismissButtonLocation - The value passed in should be a String with value "left" or "right". This value will override any values set globally with LLLocalytics.setInAppMessageDismissButtonLocation().
• dismissButtonHidden - The value passed in should be a Boolean. If false is set then no dismiss button will be rendered with the In-App. This value will override any values set globally with LLLocalytics.setInAppMessageDismissButtonHidden()

Customize In-Apps using HTML (SDK 2.3+)

As of SDK 2.3 you can modify some native elements of In App messages by modifying the index.html file of your creative. To do so, attach a data-localytics attribute to the meta name="viewport" element. The attributes should be a String containing a number of key values seperated by commas. An example might look as follows:

<html>
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" data-localytics="notch_fullscreen=true, close_button_visibility=visible, close_button_position=right, offset=50, aspect_ratio=1.5, background_alpha=0.8" />

The list of available modifications is as follows:

• notch_fullscreen (iOS Only):: Modify if the In App will render across the entirety of the screen (outside of the safe area) on devices with a notch such as the iPhone X series. If set to true, this will render into the space surrounding the notch.
• close_button_visibility: Modify the visibility of the dismiss button. Valid values are hidden and visible. This option should only be used if the creative provides it's own close button.
• close_button_position: Modify the position of the dismiss button. Valid values are right and left.
• banner_offset: Only relevant to banner In App campaigns, this key defines an offset in pixels from the top or bottom of the screen. Valid values are any positive integer value.
• aspect_ratio: Only relevant to center In App campaigns, this key modifies the aspect ratio of the native window. Valid values are any float, although we suggest keeping the range within 1.0 and 3.0.
• background_alpha: Only relevant to fullscreen and center In App campaigns, this key modifies the transparency of the native window. Valid values are any float between 0.0 (transparent) and 1.0 (opaque).

Customize Individual In-App campaigns

In order to make changes to individual campaigns, you will need to set a messaging listener in native code. In order to accomplish this please follow the documentation in the android and iOS documentation

Note: Setting a messaging listener in native code will override any values set in the previously listed customization APIs.

Properties Accessors

var campaign = localytics.campaign; // {"name": "App Upgrade Campaign", "campaignId": "449859", "eventName": "App Launch", "eventAttributes": {"isFirstSession": "NO"}};

var identifiers = localytics.identifiers; // {"customer_id": "3neRKTxbNWYKM4NJ", "first_name": "John", "last_name": "Smith", "full_name": "Sir John Smith, III", "email": "sir.john@smith.com"};

var dimensions = localytics.customDimensions; // {"c0": "Paid", "c1": "Logged In"};

var eventAttributes = localytics.attributes; // {"Team Name": "Celtics", "City": "Boston"};

var sdkVersion = localytics.libraryVersion; // "iOSa_4.3.0"

Methods

localytics.tagClickEvent("Share");

function submitNPS(ratingValue) {
  var attributes = {"Raw Rating": ratingValue};
  if (ratingValue >= 9) {
    attributes["Rating"] = "Promoter";
  } else if (ratingValue <= 6) {
    attributes["Rating"] = "Detractor";
  } else {
    attributes["Rating"] = "Neutral";
  }
  localytics.tagEvent("In-App Rating Result", attributes);
}

localytics.setCustomDimension(0, "Trial");

function formSubmit() {
  localytics.tagEvent("Form Submit", {"Email": "john@smith.com"});
  localytics.close();
}

localytics.setProfileAttribute("Favorite Team", "Red Sox", "app");

localytics.deleteProfileAttribute("Favorite Team", "app");

localytics.addProfileAttributesToSet("Favorite Team", ["Red Sox", "Celtics"], "org");

localytics.removeProfileAttributesFromSet("Favorite Team", ["Red Sox", "Celtics"], "org");

localytics.incrementProfileAttribute("Age", 1, "app");

localytics.decrementProfileAttribute("Days Until Graduation", 3, "org");

localytics.setCustomerFirstName("John");

localytics.setCustomerLastName("Smith");
    

localytics.setCustomerFullName("Sir John Smith, III");
    

localytics.setCustomerEmail("sir.john@smith.com");
    

localytics.setOptedOut([true/false]);
    

localytics.setPrivacyOptedOut([true/false]);
    

URL and Deep Link Navigation

// Opening a web URL
function openHomePage() {
  window.open("https://www.localytics.com?ampAction=click&ampExternalOpen=true");
  localytics.close();
}

// Opening a deep link URL
function openFavorites() {
  window.open("myApp://favorites?ampAction=click");
  localytics.close();
}

// Opening a deep link to the favorites page
function openFavorites() {
  window.open("myApp://favorites?ampAction=favorites");
  localytics.close();
}

// Opening a deep link to the share page
function openShare() {
  window.open("myApp://share?ampAction=share");
  localytics.close();
}

// Opening a web URL in the phone's default browser
function openHomepage() {
  window.open("https://www.localytics.com?ampAction=click&ampExternalOpen=true");
  localytics.close();
}

// Opening a web URL within the in-app message view
function openBlogInsideInApp() {
  window.open("https://info.localytics.com/blog?ampAction=click&ampExternalOpen=false");
}

// Opening another HTML file contained in the ZIP within the in-app message view
function goToFeedback() {
  window.open("feedback.html?ampAction=feedback&ampExternalOpen=false");
}

Firebase Cloud Messaging

A sample project for using Localytics with Firebase Cloud Messaging is available in our React Native samples Github repository.

dependencies {
  compile "com.google.firebase:firebase-core:11.8.0"
  compile "com.google.firebase:firebase-messaging:11.8.0"
}

import { Platform } from 'react-native';
import LLLocalytics from 'localytics-react-native';

componentDidMount() {
  if (Platform.OS === 'android') {
    LLLocalytics.registerPush();
  }
}

6. Test push integration

If you have integrated SDK version 4.1 or later, use the Rapid Push Verification page to confirm that you have integrated push correctly. Be sure to select the correct app in the dropdown at the top of the page.

Notification Channels

Android O introduced support for notification channels. These are displayed as "categories" throughout the system interface and are ways for users to subscribe to certain types of notifications that you specify.

The default channel can be configured using the localytics.xml file.

To set the proper channel id, name, and description, use the ll_default_push_channel_id, ll_default_push_channel_name, and ll_default_push_channel_description keys respectively. You can still support channels on versions of the SDK below v5.0 by modifying your app code.

Rich Push

To send rich push notifications to Android devices on React Native there is no additional setup required within your app.

Refreshing Inbox campaigns

The recommended approach to getting Inbox campaigns is by refreshing them from the Localytics server.

LLLocalytics.refreshInboxCampaigns().then((campaigns) => {
	try {
		// handle campaigns
	} catch(e) {
		console.error(e);
	}
});

LLLocalytics.refreshAllInboxCampaigns().then((campaigns) => {
	try {
		// handle campaigns
	} catch(e) {
		console.error(e);
	}
});

Get Inbox campaigns

  LLLocalytics.getDisplayableInboxCampaigns().then((campaigns) => {
    try {
// handle campaigns
    } catch(e) {
      console.error(e);
    }
  });
  

Get all Inbox campaigns

  LLLocalytics.getAllInboxCampaigns().then((campaigns) => {
    try {
// handle campaigns
    } catch(e) {
      console.error(e);
    }
  });
  

Set Inbox campaign read

LLLocalytics.setInboxCampaignRead({'campaignId': campaign.id, 'read': true});

Tag Inbox campaign impression

LLLocalytics.tagInboxImpression({'campaignId': campaign.id, 'action': 'click'});

Get Inbox campaigns unread count

  LLLocalytics.getInboxCampaignsUnreadCount().then((count) => {
    try {
// handle unread count
    } catch(e) {
      console.error(e);
    }
  });
  

1. Add the Google Play Services Location dependency

Update your project's app-level build.gradle to include the Google Play Services location dependency and the GCM dependency as follows.

dependencies {
  implementation 'com.android.support:support-compat:26.0.2'
  implementation 'com.google.android.gms:play-services-ads:11.4.2'
  implementation 'com.google.android.gms:play-services-location:11.8.0'
  implementation 'com.google.android.gms:play-services-gcm:11.8.0'
}

2. Modify AndroidManifest.xml

Add the following to your AndroidManifest.xml as follows.

1. Permissions for accessing fine location and receiving boot completed intents above the application element.

   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
   <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>
   

2. The Google Play Services version within the application element.

   <meta-data
     android:name="com.google.android.gms.version"
     android:value="@integer/google_play_services_version" />
   

3. Update the localytics.xml file

The localytics.xml file allows for easy integration of the default Localytics places receivers. Set the following keys to ensure a proper Places integration:

1. ll_places_enabled to true. This will include the Localytics LocationUpdateReceiver and BootReceiver to your manifest. These services will handle location updates, geofence triggers, and restarting location monitoring when the app is restarted.
2. ll_push_tracking_activity_enabled to true.

   If you installed the SDK manually, you will need to include the following in your manifest:

   <activity android:name="com.localytics.androidx.PushTrackingActivity"
     android:enabled="true"/>
   

   Note, that the PushTrackingActivity is launched through a pending intent that has the following flags: Intent.FLAG_ACTIVITY_NEW_TASK and Intent.FLAG_ACTIVITY_CLEAR_TASK, those two flags will ensure that if the app is running and the user presses the notification for action, the app tasks will all be closed and the PushTrackingActivity will lanch as the first activity. if you don't like this behavior and don't want your current activity to be closed you can follow this technique, And include the following in your manifest:

   <activity
       android:name="com.localytics.androidx.PushTrackingActivity"
       android:enabled="@bool/ll_push_tracking_activity_enabled"
       android:exported="false"
       android:launchMode="singleTask"
       android:taskAffinity=""
       android:excludeFromRecents="true"/>
   

3. ll_default_places_channel_id: Set this value to define the notification channel that places messaging will use if no channel is set in the dashboard.
4. ll_default_places_channel_name: Set this value to define the notification channel's name that places messaging will use if no channel is set in the dashboard. This name will be visible to the end user.
5. ll_default_places_channel_description: Set this value to define the notification channel's description that places messaging will use if no channel is set in the dashboard. The description will be visible to the user.

4. Make sure the user has the latest Google Play Services

Follow the guide on updating Google Play Services.

5. Request location permissions

Request the location permission at an appropriate time to show users a prompt as follows.

import {
  Platform,
  PermissionsAndroid,
} from 'react-native';

if (Platform.OS === 'android') {
  const granted = await PermissionsAndroid.request(
    PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,
    {
      'title': 'Location Permission',
      'message': 'Your location is needed for Places'
    }
  )
  if (granted === PermissionsAndroid.RESULTS.GRANTED) {
    console.log("Location permission granted")
  } else {
    console.log("Location permission denied")
  }
}

Opting users out

Many apps may allow their users the ability to opt out of data collection. In order to stop the Localytics SDK from collecting any additional data, customers can call:

LLLocalytics.setOptedOut(true);

Any device that has opted out in Localytics will immediately close the current session (if there is one) and tag an opt out event indicating that the device is no longer reporting any future data. Any subsequent calls that would generate a datapoint (tagEvent and setProfileAttribute for example) will be dropped. Additional detail is available in this Localytics Help article.

The opt out setting in Localytics is device specific, so if your app supports multiple users, you may want to trigger a call to setOptedOut every time a user logs in or out to update the Localytics SDK based on their previous preference.

Suppress data collection until end-user opt in

For some apps, it may be preferable to not collect any data until a user explicitly opts into data collection, or end-user consent is verified. In order to accomplish this, the app will need to update its integration such as the following:

LLLocalytics.autoIntegrate(this);
// The following method should reference a boolean value in your app that determines if the user has opted into
// data collection or not. The default (if never asked) should be false.
if (!isUserOptedIntoDataCollection()) {
  LLLocalytics.setOptedOut(true);
}

This effectively suppresses the integration until consent is verified.

GDPR

The Localytics SDK provides the following API's in SDK v2.1+:

• LLLocalytics.setPrivacyOptedOut(true) This API will delete all of the end user's data in addition to preventing any further data from being collected. This method differs from setOptedOut in that it will additionally cause Localytics to trigger a user's Right To Be Forgotten request in accordance with GDPR. This method is intended to support end user requests to be forgotten and will cease data collection.
• LLLocalytics.pauseDataUploading(true) This API will pause any data uploading to Localytics while still collecting information about the end user. It is particularly important to prevent data from being uploaded while the data collection opt-in status of an end user is still unknown. You might want to use this method if your app is configured to solicit user consent on first launch. In this case, you'd want to pause data upload until consent is granted. Once granted, the application can commence with uploads as normal. If consent is declined, you'll want to configure the app to opt-out of data collection as appropriate.
• LLLocalytics.setCustomerIdWithPrivacyOptedOut("CID", true) This API will update the current customer ID and immediately update the data collection opt-out status. This method may be used to support scenarios such as an application that, during login will verify consent via your back-end, and determine their 'forgotten' status. In that scenario this API may be called to set that user’s consent status as appropriate. We recommend you verify the the opt-in status of every user who can sign in to your application.

var optOutStatus = true; //request user information from your servers
LLLocalytics.setCustomerIdWithPrivacyOptedOut("customerId", optOutStatus)

LLLocalytics.setCustomerIdWithPrivacyOptedOut("", false);

Analytics callbacks

Analytics callbacks are useful for responding to session lifecycle and analytics events. Some potential use cases may be firing an event at the beginning or end of a session, or taking action in your app based on an auto-tagged campaign performance event in the Localytics SDK. All Localytics analytics callbacks are called on an internal background thread in the SDK, and queued onto the React main thread.

To start receiving Analytics Callbacks, you must first register for callbacks with Localytics:

var analyticsEventListener;
LLLocalytics.setAnalyticsEventsEnabled(true);
if (Platform.OS === "ios") {
  analyticsEventListener = new NativeEventEmitter(NativeModules.LLAnalyticsEmitter);
} else {
  analyticsEventListener = DeviceEventEmitter;
}

Then simply begin listening for emitted events:

analyticsEventListener.addListener('localyticsSessionWillOpen', (arg) => { 
  // args = { isFirst: BOOLEAN, isUpgrade: BOOLEAN, isResume: BOOLEAN }
  // ... do something ...
});

analyticsEventListener.addListener('localyticsSessionDidOpen', (arg) => { 
  // args = { isFirst: BOOLEAN, isUpgrade: BOOLEAN, isResume: BOOLEAN }
  // ... do something ...
});

analyticsEventListener.addListener('localyticsDidTagEvent', (arg) => { 
  // args = {"name": STRING, "attributes": OBJECT, "customerValueIncrease": NUMBER};
  // ... do something ...
});

analyticsEventListener.addListener('localyticsSessionWillClose', (arg) => { 
  // args = { }
  // ... do something ...
});

Messaging callbacks

Messaging callbacks are useful for understanding when Localytics will display messaging campaigns. This can help you prevent conflicts with other views in your app, as well as potentially suppress the Localytics display. All Localytics messaging callbacks are called on the main thread.

There are two ways to register for Messaging Callbacks with Localytics. The first will allow you to receive updates from Localytics in Javascript. The second will allow you to modify the behavior of messaging campaigns before they are displayed.

• Receiving callbacks in Javascript

  To start receiving Messaging Callbacks, you must first register for callbacks with Localytics:

  var messagingEventListener;
  LLLocalytics.setAnalyticsEventsEnabled(true);
  if (Platform.OS === "ios") {
    messagingEventListener = new NativeEventEmitter(NativeModules.LLMessagingEmitter);
  } else {
    messagingEventListener = DeviceEventEmitter;
  }
  

  Then simply begin listening for emitted events:

  messagingEventListener.addListener('localyticsShouldShowInAppMessage', (arg) => { 
    // args = { "campaign": OBJECT, "shouldShow": BOOLEAN }
    // ... do something ...
  });
  
  messagingEventListener.addListener('localyticsShouldDelaySessionStartInAppMessages', (arg) => { 
    // args = { "shouldDelay": BOOLEAN }
    // ... do something ...
  });
  
  messagingEventListener.addListener('localyticsWillDisplayInAppMessage', (arg) => { 
    // args = { "campaign": OBJECT }
    // ... do something ...
  });
  
  messagingEventListener.addListener('localyticsWillDismissInAppMessage', (arg) => { 
    // args = { }
    // ... do something ...
  });
  
  messagingEventListener.addListener('localyticsDidDismissInAppMessage', (arg) => { 
    // args = { }
    // ... do something ...
  });
  
  messagingEventListener.addListener('localyticsShouldDisplayPlacesCampaign', (arg) => { 
    // args = { "campaign": OBJECT, "shouldShow": BOOLEAN }
    // ... do something ...
  });
  
  messagingEventListener.addListener('localyticsWillShowPlacesPushNotification', (arg) => { 
    // args = { "campaign": OBJECT }
    // ... do something ...
  });
  
  messagingEventListener.addListener('localyticsShouldShowPushNotification', (arg) => { 
    // args = { "campaign": OBJECT, "shouldShow": BOOLEAN }
    // ANDROID ONLY
    // ... do something ...
  });
  
  messagingEventListener.addListener('localyticsWillShowPushNotification', (arg) => { 
    // args = { "campaign": OBJECT }
    // ANDROID ONLY
    // ... do something ...
  });
  
  messagingEventListener.addListener('localyticsDiyInAppMessage', (arg) => { 
    // args = { "campaign": OBJECT }
    // ... Handle the rendering of your own In App campaign. This should be paired with the next section on Modifying Messaging Behavior ...
  });
  
  messagingEventListener.addListener('localyticsDiyPlacesPushNotification', (arg) => { 
    // args = { "campaign": OBJECT }
    // ... Handle the rendering of your own Places campaign. This should be paired with the next section on Modifying Messaging Behavior ...
  });
  
  messagingEventListener.addListener('localyticsDiyPushNotification', (arg) => { 
    // args = { "campaign": OBJECT }
    // ANDROID ONLY
    // ... Handle the rendering of your own Push campaign. This should be paired with the next section on Modifying Messaging Behavior ...
  });
  

• Modifying messaging behavior

  Localytics provides a way to modify Places, In-App, and Push campaigns:

  • In-App Campaigns can be modified as follows:

    LLLocalytics.setInAppMessageConfiguration({
      "shouldShow": BOOLEAN // if set to false, this will suppress all In-App messages.
      "diy": BOOLEAN // if set to false, Localytics will not render the In-App and will call localyticsDiyInAppMessage
      "aspectRatio": NUMBER // The Aspect Ratio for a Centered In App Campaign
      "backgroundAlpha": NUMBER // The transparency for a Full Screen In App Campaign between 0 (transparent) and 1 (opaque)
      "bannerOffsetDps": NUMBER // The pixel offset for Banner In App campaigns
      "dismissButtonLocation": STRING // Location of the In-App Dismiss Button ("left" or "right")
      "dismissButtonHidden": BOOLEAN // Indicate if the Localytics SDK should show a dismiss button
    });
    

  • Places Campaigns can be modified as follows:

    LLLocalytics.setPlacesMessageConfiguration({
      "shouldShow": BOOLEAN // if set to false, this will suppress all Places messages.
      "diy": BOOLEAN // if set to false, Localytics will not render the Places message and will call localyticsDiyPlacesPushNotification
      
      // Android only keys
    
      "category": STRING // the notification category that should be attached to this message.
      "color": NUMBER // the color of the notification
      "contentInfo": STRING // the content info of the notification
      "contentTitle": STRING // the title of the notification
      "defaults": OBJECT // the defaults for notification interruption.  Possible object values include "lights", "sound", "vibrate", and "all"
      "priority": NUMBER // the priority of the notification
      "sound": STRING // the sound as a URI to a sound file on your device
      "vibrate": ARRAY // the vibration pattern for this notification
    
      // iOS only keys
    
      "title": STRING // the title of the notification
      "subtitle": STRING // the subtitle of the notification
      "badge": NUMBER // the badge number this notification should update the app with.
      "sound": STRING // iOS 10+ ONLY - the name of a sound in your App Bundle
      "launchImageName": STRING // The launch image name 
    });
    

  • Push Campaigns can be modified on Android as follows:

    LLLocalytics.setPushMessageConfiguration({
      "shouldShow": BOOLEAN // if set to false, this will suppress all Places messages.
      "diy": BOOLEAN // if set to false, Localytics will not render the Places message and will call localyticsDiyPlacesPushNotification
    
      "category": STRING // the notification category that should be attached to this message.
      "color": NUMBER // the color of the notification
      "contentInfo": STRING // the content info of the notification
      "contentTitle": STRING // the title of the notification
      "defaults": OBJECT // the defaults for notification interruption.  Possible object values include "lights", "sound", "vibrate", and "all"
      "priority": NUMBER // the priority of the notification
      "sound": STRING // the sound as a URI to a sound file on your device
      "vibrate": ARRAY // the vibration pattern for this notification
    });
    

Location Callbacks

Location callbacks are useful for understanding when Localytics responds location changes. localyticsDidUpdateLocation is called on an internal background thread; the others are called on the main thread.

To start receiving Location Callbacks, you must first register for callbacks with Localytics:

var locationEventListener;
LLLocalytics.setLocationEventsEnabled(true);
if (Platform.OS === "ios") {
  locationEventListener = new NativeEventEmitter(NativeModules.LLLocationEmitter);
} else {
  locationEventListener = DeviceEventEmitter;
}

Then simply begin listening for emitted events:

locationEventListener.addListener('localyticsDidUpdateLocation', (arg) => { 
  // args = { "location": { 
    "latitude": NUMBER, 
    "longitude": NUMBER, 
    "altitude": NUMBER (iOS ONLY)
    "time": NUMBER (iOS ONLY)
    "horizontalAccuracy": NUMBER (iOS ONLY) 
    "verticalAccuracy": NUMBER (iOS ONLY)
    "uniqueId": STRING (ANDROID ONLY)
    "name": STRING (ANDROID ONLY)
    "type": STRING (ANDROID ONLY)
    "attributes": OBJECT (ANDROID ONLY)
    "originLocation": STRING (ANDROID ONLY)
    "radius": NUMBER (ANDROID ONLY)
  }}
  // ... do something ...
});

locationEventListener.addListener('localyticsDidTriggerRegions', (arg) => { 
  // args = { 
    "event": STRING ("enter" or "exit"), 
    regions": ARRAY (Of Objects) [ {
      "uniqueId": STRING
      "latitude": NUMBER
      "longitude": NUMBER
      "name": STRING
      "type": STRING (ANDROID ONLY)
      "originLocation": STRING (ANDROID ONLY)
      "radius": NUMBER (ANDROID ONLY)
      "attributes": OBJECT
    } ... ] 
  }
  // ... do something ...
});

locationEventListener.addListener('localyticsDidUpdateMonitoredGeofences', (arg) => { 
  // args = {
    "added": ARRAY [ {
      "uniqueId": STRING
      "latitude": NUMBER
      "longitude": NUMBER
      "name": STRING
      "type": STRING (ANDROID ONLY)
      "originLocation": STRING (ANDROID ONLY)
      "radius": NUMBER (ANDROID ONLY)
      "attributes": OBJECT
    }, ... ], 
    "removed": [ {
      "uniqueId": STRING
      "latitude": NUMBER
      "longitude": NUMBER
      "name": STRING
      "type": STRING (ANDROID ONLY)
      "originLocation": STRING (ANDROID ONLY)
      "radius": NUMBER (ANDROID ONLY)
      "attributes": OBJECT
    }, ...]
  };
  // ... do something ...
});

Call To Action Callbacks

Added in SDK 2.2, Call To Action callbacks are useful for understanding when Localytics has triggered a deeplink or internal event through a javascript API.

To start receiving CallToAction Callbacks, you must first register for callbacks with Localytics:

var ctaEventListener;
LLLocalytics.setCallToActionEventsEnabled(true);
if (Platform.OS === "ios") {
  ctaEventListener = new NativeEventEmitter(NativeModules.LLCallToActionEmitter);
} else {
  ctaEventListener = DeviceEventEmitter;
}

Then simply begin listening for emitted events:

ctaEventListener.addListener('localyticsShouldDeeplink', (arg) => { 
  // args = { url: STRING, campaign: OBJECT }
  // ... do something ...
});

ctaEventListener.addListener('localyticsDidOptOut', (arg) => { 
  // args = { optedOut: BOOLEAN, campaign: OBJECT }
  // ... do something ...
});

ctaEventListener.addListener('localyticsDidPrivacyOptOut', (arg) => { 
  // args = { optedOut: BOOLEAN, campaign: OBJECT }
  // ... do something ...
});

ctaEventListener.addListener('localyticsShouldPromptForLocationWhenInUsePermissions', (arg) => { 
  // args = { campaign: OBJECT }
  // iOS ONLY
  // ... do something ...
});

ctaEventListener.addListener('localyticsShouldPromptForLocationAlwaysPermissions', (arg) => { 
  // args = { campaign: OBJECT }
  // iOS ONLY
  // ... do something ...
});

ctaEventListener.addListener('localyticsShouldPromptForNotificationPermissions', (arg) => { 
  // args = { campaign: OBJECT }
  // iOS ONLY
  // ... do something ...
});

ctaEventListener.addListener('localyticsShouldPromptForLocationPermissions', (arg) => { 
  // args = { campaign: OBJECT }
  // ANDROID ONLY
  // ... do something ...
});