Android

Installing with Maven

The fastest and easiest way to use Localytics in your project is with Maven.

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

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

2. In your project's app-level build.gradle, add dependencies for Localytics, Android Support v4, and Google Mobile Ads.

   dependencies {
     implementation 'com.android.support:support-compat:28.0.0'
     implementation 'com.localytics.androidx:library:6.2+'
     implementation 'com.google.android.gms:play-services-ads:16.0.0'
     implementation 'com.android.installreferrer:installreferrer:1.1'
   }
   

Manual Installation

If you do not wish to use Maven, you can manually include the Localytics package in your project.

1. Download the latest version of the SDK here.

2. Unzip the archive and drag the JAR into your project's libs directory.

3. Update your project's app-level build.gradle to add dependencies for the Localytics JAR, Android Support v4, and Google Mobile Ads as follows.

   dependencies {
     implementation files('libs/localytics.jar')
     implementation 'com.android.support:support-compat:28.0.0'
     implementation 'com.google.firebase:firebase-messaging:17.1.0'
     implementation 'com.google.android.gms:play-services-ads:16.0.0'
     implementation 'com.android.installreferrer:installreferrer:1.1'
   }
   

4. Add the following to your AndroidManifest.xml:

   1. Localytics ReferralReceiver within the application element:

      <receiver
        android:name="com.localytics.androidx.ReferralReceiver"
        android:exported="true">
        <intent-filter>
          <action android:name="com.android.vending.INSTALL_REFERRER" />
        </intent-filter>
      </receiver>
      

   2. Permissions above the application element:

      <uses-permission android:name="android.permission.INTERNET" />
      <uses-permission android:name="android.permission.WAKE_LOCK" />
      

   3. Localytics LocationUpdateReceiver to be able to receive location updates:

      <receiver android:name="com.localytics.androidx.LocationUpdateReceiver"/>
      

5. If you are building your app using Proguard, update your project's proguard-rules.pro to include Localytics exceptions as follows.

   -keep class com.localytics.androidx.** { *; }
   -keepattributes JavascriptInterface
   -dontwarn com.localytics.androidx.**
   

Uploading Data

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 omit any or all in keys from your localytics.xml file. If you would like to disable scheduled uploads, set -1 as the value for all keys.

To specify your custom upload intervals, update the localytics.xml file with the following keys.

• ll_wifi_upload_interval_seconds Configure the interval at which the Localytics SDK will attempt to upload data in the case of a WiFi connection. Having a WiFi connection will supersede any mobile data connection. Default value is 5 seconds.
• ll_great_network_upload_interval_seconds Configure the interval at which the Localytics SDK will attempt to upload data in the case of 4G or LTE connections. Default value is 10 seconds.
• ll_decent_network_upload_interval_seconds Configure the interval at which the Localytics SDK will attempt to upload data in the case of a 3G connection. Default value is 30 seconds.
• ll_bad_network_upload_interval_seconds Configure the interval at which the Localytics SDK will attempt to upload data in the case of 2G or EDGE connections. Default value is 90 seconds.

Build Variants

Many apps find it useful to be able to ship with different app keys or configurations for different app types. The localytics.xml can support this by taking advantage of Android's build variants and product flavors. Simply include one localytics.xml in each build variant or product flavor, and modify the resources inside of it as you desire.

Purchased

Localytics.tagPurchased("Shirt", "sku-123", "Apparel", 15, extraAttributes);

Added to Cart

Localytics.tagAddedToCart("Shirt", "sku-123", "Apparel", 15, extraAttributes);

Started Checkout

Localytics.tagStartedCheckout(50, 2, extraAttributes);

Completed Checkout

Localytics.tagCompletedCheckout(50, 2, extraAttributes);

Content Viewed

Localytics.tagContentViewed("Top 10", "e8z7319zbe", "Article", extraAttributes);

Searched

Localytics.tagSearched("Celtics", "Sports", 15, extraAttributes);

Shared

Localytics.tagShared("Top 10", "e8z7319zbe", "Article", "Twitter", extraAttributes);

Content Rated

Localytics.tagContentRated("Headlines", "8a4z5j9q", "Song", 5, extraAttributes);

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.

Java Kotlin

Localytics.tagCustomerRegistered(new Customer.Builder()
    .setCustomerId("3neRKTxbNWYKM4NJ")
    .setFirstName("John")
    .setLastName("Smith")
    .setFullName("Sir John Smith, III")
    .setEmailAddress("sir.john@smith.com")
    .build(),
    "Facebook",
    extraAttributes
);

Localytics.tagCustomerRegistered(
  Customer.Builder()
      .setCustomerId("3neRKTxbNWYKM4NJ")
      .setFirstName("John")
      .setLastName("Smith")
      .setFullName("Sir John Smith, III")
      .setEmailAddress("sir.john@smith.com")
      .build(),
  "Facebook",
  extraAttributes
)

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.

Java Kotlin

Localytics.tagCustomerLoggedIn(new Customer.Builder()
    .setCustomerId("3neRKTxbNWYKM4NJ")
    .setFirstName("John")
    .setLastName("Smith")
    .setFullName("Sir John Smith, III")
    .setEmailAddress("sir.john@smith.com")
    .build(),
    "Native",
    extraAttributes
);

Localytics.tagCustomerLoggedIn(
  Customer.Builder()
      .setCustomerId("3neRKTxbNWYKM4NJ")
      .setFirstName("John")
      .setLastName("Smith")
      .setFullName("Sir John Smith, III")
      .setEmailAddress("sir.john@smith.com")
      .build(),
  "Facebook",
  extraAttributes
)

Customer Logged Out

Localytics.tagLoggedOut(extraAttributes);

Invited

Localytics.tagInvited("SMS", extraAttributes);

Numeric value

Localytics.setProfileAttribute("Age", 45, Localytics.ProfileScope.ORGANIZATION);

Numeric values in a set

Java Kotlin

Localytics.setProfileAttribute(
	"Lucky numbers",
	new long[]{8, 13},
	Localytics.ProfileScope.APPLICATION
);
					

Localytics.setProfileAttribute(
	"Lucky numbers",
	longArrayOf(8, 13),
	Localytics.ProfileScope.APPLICATION
)
					

Date value

Java Kotlin

Localytics.setProfileAttribute(
	"Birthday", 
	new GregorianCalendar(1962, 11, 23).getTime(), 
	Localytics.ProfileScope.ORGANIZATION
);
					

Localytics.setProfileAttribute(
	"Birthday",
	GregorianCalendar(1962, 11, 23).time,
	Localytics.ProfileScope.ORGANIZATION
)
					

Date values in a set

Java Kotlin

Localytics.setProfileAttribute(
	"Upcoming Milestone Dates", 
	new Date[]{
		new GregorianCalendar(2015, 10, 1).getTime(),
		new GregorianCalendar(2016, 3, 17).getTime()
	}, 
	Localytics.ProfileScope.APPLICATION
);
					

Localytics.setProfileAttribute(
	"Upcoming Milestone Dates", arrayOf<Date>(
			GregorianCalendar(2015, 10, 1).time,
			GregorianCalendar(2016, 3, 17).time
	),
	Localytics.ProfileScope.APPLICATION
)
					

String value

Localytics.setProfileAttribute(
	"Hometown",
	"New York, New York",
	Localytics.ProfileScope.ORGANIZATION
);
			

String values in a set

Java Kotlin

Localytics.setProfileAttribute(
	"States visited", 
	new String[]{
		"New York",
		"California",
		"South Dakota"
	},
	Localytics.ProfileScope.APPLICATION
);
					

Localytics.setProfileAttribute(
	"States visited",
	arrayOf(
		"New York",
		"California",
		"South Dakota"
	),
	Localytics.ProfileScope.APPLICATION
)
					

Adding a numeric value to a set

Java Kotlin

Localytics.addProfileAttributesToSet(
	"Lucky numbers",
	new long[]{8,13},
	Localytics.ProfileScope.APPLICATION
);
					

Localytics.addProfileAttributesToSet(
	"Lucky numbers",
	longArrayOf(8, 13),
	Localytics.ProfileScope.APPLICATION
)
					

Adding a date value to a set

Java Kotlin

Localytics.addProfileAttributesToSet(
	"Upcoming Milestone Dates", 
	new Date[]{
		new GregorianCalendar(2015, 4, 19).getTime(),
		new GregorianCalendar(2015, 12, 24).getTime()
	},
	Localytics.ProfileScope.APPLICATION
);
					

Localytics.addProfileAttributesToSet(
	"Upcoming Milestone Dates",
	arrayOf<Date>(
		GregorianCalendar(2015, 4, 19).time,
		GregorianCalendar(2015, 12, 24).time
	),
	Localytics.ProfileScope.APPLICATION
)
					

Adding a string value to a set

Java Kotlin

Localytics.addProfileAttributesToSet(
	"States visited",
	new String[]{"North Dakota", "South Dakota"},
	Localytics.ProfileScope.APPLICATION
);
					

Localytics.addProfileAttributesToSet(
	"States visited",
	arrayOf("North Dakota", "South Dakota"),
	Localytics.ProfileScope.APPLICATION
)
					

Removing numeric values from a set

Java Kotlin

Localytics.removeProfileAttributesFromSet(
	"Lucky numbers",
	new long[]{8,13},
	Localytics.ProfileScope.APPLICATION
);
					

Localytics.removeProfileAttributesFromSet(
	"Lucky numbers",
	longArrayOf(8, 13),
	Localytics.ProfileScope.APPLICATION
)
					

Removing date values from a set

Java Kotlin

Localytics.removeProfileAttributesFromSet(
	"Upcoming Milestone Dates", 
	new Date[]{
		new GregorianCalendar(2015, 4, 19).getTime(),
		new GregorianCalendar(2015, 12, 24).getTime()
	},
	Localytics.ProfileScope.APPLICATION
);
					

Localytics.removeProfileAttributesFromSet(
	"Upcoming Milestone Dates",
	arrayOf<Date>(
		GregorianCalendar(2015, 4, 19).time,
		GregorianCalendar(2015, 12, 24).time
	),
	Localytics.ProfileScope.APPLICATION
)
					

Removing string values from a set

Java Kotlin

Localytics.removeProfileAttributesFromSet(
	"States visited",
	new String[]{"North Dakota", "South Dakota"},
	Localytics.ProfileScope.APPLICATION
);
					

Localytics.removeProfileAttributesFromSet(
	"States visited",
	arrayOf("North Dakota", "South Dakota"),
	Localytics.ProfileScope.APPLICATION
)
					

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 [Localytics.tagEvent_Name] you will use the following

Localytics.triggerInAppMessage("Item Purchased");

Marketing triggers with attributes

To create a trigger with additional attribute conditions, use

Java Kotlin

Map<String, String> values = new HashMap<String, String>();
values.put("Item Name", "Stickers");
Localytics.triggerInAppMessage("Item Purchased", values);
          

Localytics.triggerInAppMessage("Item Purchased", mapOf(
  "Item Name" to "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 image

By default, there is a dismiss button in the shape of an "X" on the top-left of the in-app message dialog. Use the methods below to set the dismiss button to a different image or to change the position of the button to the top-right. If you change the image, the Localytics SDK creates a copy of the referenced image based on the maximum allowed image size, so your app doesn't have to keep the image after the call.

To set the image by name, use

Java Kotlin

Bitmap bitmap = getBitmapFromAsset("your-customized-dismiss-button.png");
Localytics.setInAppMessageDismissButtonImage(getResources(), bitmap);
          

val bitmap: Bitmap = getBitmapFromAsset("your-customized-dismiss-button.png")
Localytics.setInAppMessageDismissButtonImage(resources, bitmap)
					

To set the image by image, use

Localytics.setInAppMessageDismissButtonImage(getResources(), R.drawable.your_customized_dismiss_button);

If you want to clear the image and switch back to the default, pass a null to this method as below.

Localytics.setInAppMessageDismissButtonImage(getResources(), null);

Customizing the dismiss button location

To set the dismiss button location to the left, use

Localytics.setInAppDismissButtonLocation(Localytics.InAppMessageDismissButtonLocation.LEFT);

To set the dismiss button location to the right, use

Localytics.setInAppDismissButtonLocation(Localytics.InAppMessageDismissButtonLocation.RIGHT);

Customize In-Apps using HTML (SDK 5.4+)

As of SDK 5.4 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 video_conversion_percentage=80" />

The list of available modifications is as follows:

• 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 density independent pixel 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. Starting in SDK 5.6, this attribute also applies to banner campaigns.
• 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).
• notch_fullscreen: Only available in SDK 5.6 and up - Only relevant to fullscreen In App campaigns, this key modifies 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 Pixel 3 XL. If set to true, this will render into the space surrounding the notch.
• video_conversion_percentage: Only available in SDK 5.7 and up - If a video is present in the campaign, this sets a percentage of the video, that is watched will trigger the Localytics SDK to tag a Localytics Video Played event.

Customize In-Apps with a Callback

Using a messaging callback, as described in the advanced section, can allow for customization of individual in-apps right before they are shown to the user. The list of configurable properties are available on an object passed through the callback, the InAppConfiguration. Modification of these values will result in different displays for an individual creative. The list is as follows:

• Aspect Ratio: 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 and banner creatives in SDK 5.6+.
• Offset: 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.
• Background Alpha: The value passed in should be a float value between 0.0 (transparent) and 1.0 (opaque).
• Dismiss Button Image: The values passed in should be a reference to the app's Resource and either a Bitmap or a resource ID. This value will override any values set globally with Localytics.setInAppMessageDismissButtonImage().
• Dismiss Button Location: The value passed in should be either InAppMessageDismissButtonLocation.LEFT for in-app creatives with a dismiss button on the left, or InAppMessageDismissButtonLocation.RIGHT for in-app creatives with a dismiss button on the right. This value will override any values set globally with Localytics.setInAppMessageDismissButtonLocation().
• Dismiss Button Visibility: The value passed in should be an int corresponding to the values of View.GONE, View.INVISIBLE, or View.VISIBLE. If View.GONE or View.INVISIBLE is passed in then the dismiss button will be hidden for this in app creative.

A simple example of using the callbacks to modify an in-app creative may look as follows:

Java Kotlin

@NonNull
@Override
public InAppConfiguration localyticsWillDisplayInAppMessage(@NonNull final InAppCampaign campaign, @NonNull final InAppConfiguration configuration) {
  if (configuration.isCenterCampaign()) {
    configuration.setAspectRatio(1.2f);
  } else if (configuration.isTopBannerCampaign() || configuration .isBottomBannerCampaign()) {
    configuration.setBannerOffsetDps(50);
  }
  configuration.setBackgroundAlpha(0f);
    
  configuration.setDismissButtonImage(getResources(), R.id.dismiss_button_image);
  configuration.setDismissButtonLocation(Localytics.InAppMessageDismissButtonLocation.RIGHT);
  configuration.setDismissButtonVisibility(View.VISIBLE);
    
  return configuration;
}
          

fun localyticsWillDisplayInAppMessage(campaign: InAppCampaign, configuration: InAppConfiguration): InAppConfiguration {
  if (configuration.isCenterCampaign()) {
    configuration.setAspectRatio(1.2f)
  } else if (configuration.isTopBannerCampaign() || configuration.isBottomBannerCampaign()) {
    configuration.setBannerOffsetDps(50)
  }
  configuration.setBackgroundAlpha(0f)
  configuration.setDismissButtonImage(resources, R.id.dismiss_button_image)
  configuration.setDismissButtonLocation(Localytics.InAppMessageDismissButtonLocation.RIGHT)
  configuration.setDismissButtonVisibility(View.VISIBLE)
  return configuration
}
          

Properties Accessors

• localytics.campaign (Only available on SDK 4.3 and later): Returns a Javascript object containing information about the campaign that triggered this In-App message. The javascript object contains the campaign name as it would appear on the dashboard (name), the campaign ID (campaignId), the name of the event that triggered the In-App (eventName), and the attribute keys and values tagged on the event or trigger that launched the in-app message (eventAttributes).

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

• localytics.identifiers: Returns a Javascript object containing a user's identifying data: customer_id, first_name, last_name, full_name, and email. Note: These values will only be populated if you have set them for the user directly via the SDK.

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

• localytics.customDimensions: Returns a Javascript object containing the current session's custom dimensions. The keys of the object will be "c0", "c1", etc. for dimensions that have been set.

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

• localytics.attributes: Returns a Javascript object containing the attribute keys and values tagged on the event or trigger that launched the in-app message.

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

• localytics.libraryVersion: Returns the Localytics SDK version as a string.

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

Methods

• localytics.tagClickEvent(action) (Only available on SDK 4.3 and later): Tags an in-app clickthrough (also kown as a conversion) with an optional action attribute. If the action attribute is omitted, the default of click will be used. This method can only be called once per in-app. The first time this method is called an event will be recorded, and any subsequent calls will be ignored.

  localytics.tagClickEvent("Share");
  

• localytics.tagEvent(event, attributes, customerValueIncrease): Tags an event with optional attributes and an optional custom value increase.

  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(index, value): Sets a custom dimension value for a particular index.

  localytics.setCustomDimension(0, "Trial");
  

• localytics.close(): Closes the in-app. If an in-app message viewed event hasn't been tagged (i.e. ampView), an event with ampAction equal to "X" will be tagged.

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

• localytics.setProfileAttribute(name, value, scope) (Only available on SDK 4.3 and later): Sets a profile attribute with an optional scope ("app" or "org").

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

• localytics.deleteProfileAttribute(name, scope) (Only available on SDK 4.3 and later): Delete a profile attribute with an optional scope ("app" or "org").

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

• localytics.addProfileAttributesToSet(name, values, scope) (Only available on SDK 4.3 and later): Add profile attributes with an optional scope ("app" or "org").

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

• localytics.removeProfileAttributesFromSet(name, values, scope) (Only available on SDK 4.3 and later): Remove profile attributes with an optional scope ("app" or "org").

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

• localytics.incrementProfileAttribute(name, value, scope) (Only available on SDK 4.3 and later): Increment a profile attribute with an optional scope ("app" or "org").

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

• localytics.decrementProfileAttribute(name, value, scope) (Only available on SDK 4.3 and later): Decrement a profile attribute with an optional scope ("app" or "org").

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

• localytics.setCustomerFirstName(name, value, scope) (Only available on SDK 4.3 and later): Set the user's first name.

  localytics.setCustomerFirstName("John");
  

• localytics.setCustomerLastName(name, value, scope) (Only available on SDK 4.3 and later): Set the user's last name.

  localytics.setCustomerLastName("Smith");
      
  

• localytics.setCustomerFullName(name, value, scope) (Only available on SDK 4.3 and later): Set the user's full name.

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

• localytics.setCustomerEmail(name, value, scope) (Only available on SDK 4.3 and later): Set the user's email.

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

• localytics.setOptedOut(optedOut) (Only available on SDK 5.2 and later): Opt the user into or out of data collection. See the advanced section for more details on the implications of this call.

  localytics.setOptedOut([true/false]);
      
  

• localytics.setPrivacyOptedOut(optedOut) (Only available on SDK 5.2 and later): Opt the user into or out of data collection. See the advanced section for more details on the implications of this call.

  localytics.setPrivacyOptedOut([true/false]);
      
  

• localytics.getIdentifiers() (Only available on SDK 5.2 and later): Returns a String representing a Javascript object that contains a user's identifying data: customer_id, first_name, last_name, full_name, and email. Note: These values will only be populated if you have set them for the user directly via the SDK. To retrieve values from this object, you will need to call JSON.parse().

  var localyticsIdentifiers = JSON.parse(localytics.getIdentifiers()); //{"customer_id": "3neRKTxbNWYKM4NJ", "first_name": "John", "last_name": "Smith", "full_name": "Sir John Smith, III", "email": "sir.john@smith.com"};
            
  

• localytics.getIdentifier(identifier) (Only available on SDK 5.2 and later): Returns the specific value that corresponds to the identifier requested, or null if nothing has been set. Possible keys include: customer_id, first_name, last_name, full_name,and email. Note: These values will only be populated if you have set them for the user directly via the SDK.

  var customerId = localytics.getIdentifier('customer_id'); //"3neRKTxbNWYKM4NJ"
            
  

• localytics.getCustomDimensions() (Only available on SDK 5.2 and later): Returns a String representing a Javascript object that contains the custom dimensions that have been set for this device. Keys for this dictionary can be values between c0 and c19. Note: These values will only be populated if you have set them for the device directly via the SDK. To retrieve values from this object, you will need to call JSON.parse().

  var localyticsCustomDimensions = JSON.parse(localytics.getCustomDimensions());
  var customDimension1 = localyticsCustomDimensions['c1']; // {"c0": "Paid", "c1": "Logged In"};
            
  

• localytics.getCustomDimension(dimension) (Only available on SDK 5.2 and later): Returns the specific value that corresponds to the dimension requested, or null if nothing has been set. Note: These values will only be populated if you have set them for the user directly via the SDK.

  var customDimension1 = localytics.getCustomDimension(1); //"Logged In"
            
  

• localytics.getEventAttributes() (Only available on SDK 5.2 and later): Returns a String representing a Javascript object that contains the attribute keys and values tagged on the event or trigger that launched the in-app message. Note: To retrieve values from this object, you will need to call JSON.parse().

  var localyticsEventAttributes = JSON.parse(localytics.getEventAttributes()); // {"Team Name": "Celtics", "City": "Boston"};
            
  

• localytics.getCampaign() (Only available on SDK 5.2 and later): Returns a String representing a Javascript object that contains information about the campaign that triggered this In-App message. The javascript object contains the campaign name as it would appear on the dashboard (name), the campaign ID (campaignId), the name of the event that triggered the In-App (eventName), and the attribute keys and values tagged on the event or trigger that launched the in-app message (eventAttributes). Note: To retrieve values from this object, you will need to call JSON.parse().

  var localyticsCamapign = JSON.parse(localytics.getCampaign()); // {"name": "App Upgrade Campaign", "campaignId": "449859", "eventName": "App Launch", "eventAttributes": {"isFirstSession": "NO"}};
            
  

• localytics.getLibraryVersion() (Only available on SDK 5.2 and later): Returns the Localytics SDK version as a string.

  var libraryVersion = localytics.getLibraryVersion(); //"androida_5.2.0"
            
  

• localytics.getLocationAuthorizationStatus() (Only available on SDK 5.3 and later): Returns the devices current location authorization status (true/false).

  var locationAuthorized = localytics.getLocationAuthorizationStatus(); //"true"
            
  

• localytics.getNotificationAuthorizationStatus() (Only available on SDK 5.3 and later): Returns the devices current notification authorization status (true/false).

  var locationAuthorized = localytics.getNotificationAuthorizationStatus(); //"true"
            
  

• localytics.getSystemGestureInsets() (Only available on SDK 5.6 and later): Returns a String representing a Javascript object that contains the devices system gesture insets, or the area of the device that touch events may be overridden by system gestures. The value is a representation in pixels that may be affected from the edge of the device. It may be best to ensure certain UI elements (such as sliders) are not rendered into this area.

  s

  var systemGestureInsets = JSON.parse(localytics.getSystemGestureInsets()); //{"top": 0, "bottom": 0, "left": 100, "right": 0};
            
  

• localytics.promptForLocationPermissions(action) (Only available on SDK 5.2 and later): Prompt the user for location permissions using the OS specific permission prompt. This method can only be called once per in-app. The first time this method is called it will tag a conversion event with the action parameter, prompt the user for location permissions, and then dismiss the In-App. If the action attribute is omitted, the default of click will be used as the conversion event.

  localytics.promptForLocationPermissions("Location Prompt Accepted");
            
  

  This method will not prompt the user for Location permissions if any of the following are true:

  • If the AndroidManifest.xml is missing the permission android.permission.ACCESS_FINE_LOCATION
  • If the permission has already been granted.
  • If the permission has been denied and the user has requested that no more prompts be shown.

• localytics.promptForLocationAlwaysPermissions(action) (Only available on SDK 5.6 and later): Prompt the user for background location permissions on Android Q using the OS specific permission prompt. This method can only be called once per In-App. The first time this method is called it will tag a conversion event with the action parameter, prompt the user for location permissions, and then dismiss the In-App. If the action attribute is omitted, the default of click will be used as the conversion event.

  localytics.promptForLocationAlwaysPermissions("Location Prompt Accepted");
            
  

  This method will not prompt the user for Location permissions if any of the following are true:

  • If the AndroidManifest.xml is missing the permission android.permission.ACCESS_FINE_LOCATION or android.permission.ACCESS_BACKGROUND_LOCATION
  • If the permissions have already been granted.
  • If the permissions have been denied and the user has requested that no more prompts be shown.

• localytics.promptForLocationWhenInUsePermissions(action) (Only available on SDK 5.6 and later): Prompt the user for location permissions when the app is in use using the OS specific permission prompt. This method can only be called once per in-app. The first time this method is called it will tag a conversion event with the action parameter, prompt the user for location permissions, and then dismiss the In-App. If the action attribute is omitted, the default of click will be used as the conversion event.

  localytics.promptForLocationWhenInUsePermissions("Location Prompt Accepted");
            
  

  This method will not prompt the user for Location permissions if any of the following are true:

  • If the AndroidManifest.xml is missing the permission android.permission.ACCESS_FINE_LOCATION
  • If the the permission has already been granted.
  • If the the permission has been denied and the user has requested that no more prompts be shown.

• localytics.deeplinkToSettings(action) (Only available on SDK 5.3 and later): Trigger a deeplink to the phone's settings screen. This method can only be called once per in-app. The first time this method is called it will tag a conversion event with the action parameter and then deeplink to the settings page. If the action attribute is omitted, the default of click will be used as the conversion event.

  localytics.deeplinkToSettings("Deeplink");
            
  

• localytics.deeplinkToNotificationSettings(action) (Only available on SDK 5.3 and later): Trigger a deeplink to the phone's notification specific settings screen. This method can only be called once per in-app. The first time this method is called it will tag a conversion event with the action parameter and then deeplink to the notification specific settings page. If the action attribute is omitted, the default of click will be used as the conversion event.

  localytics.deeplinkToNotificationSettings("Deeplink");
            
  

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");
}

1. Add Firebase to your Android project

Follow the instructions for Adding Firebase to your Android project. Ensure that you have followed both steps for Adding Firebase to your app and Adding the SDK.

2. Add the Firebase Cloud Messaging dependency

Update your project's app-level build.gradle to include the dependency for Firebase Cloud Messaging (FCM) as follows.

dependencies {
  implementation 'com.android.support:support-compat:26.0.2'
  implementation 'com.google.firebase:firebase-messaging:17.1.0'
  implementation 'com.google.android.gms:play-services-ads:16.0.0'
  implementation 'com.localytics.androidx:library:6.2+'
  implementation 'com.android.installreferrer:installreferrer:1.1'
}

3. Update the localytics.xml file

The localytics.xml file allows for easy integration of the default Localytics Firebase receivers. Set the following keys to ensure a proper push integration depending on your installation:

1. ll_fcm_push_services_enabled to true. If you installed via Maven, Localytics FirebaseTokenService and FirebaseService will be included in your manifest. These services will handle collecting of push tokens as well as the rendering of incoming notifications from FCM.

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

   <service android:name="com.localytics.androidx.FirebaseTokenService"
       android:exported="true"
       android:enabled="true">
     <intent-filter>
       <action android:name="com.google.firebase.INSTANCE_ID_EVENT"/>
     </intent-filter>
   </service>
   
   <service android:name="com.localytics.androidx.FirebaseService"
       android:exported="true"
       android:enabled="true">
     <intent-filter>
       <action android:name="com.google.firebase.MESSAGING_EVENT"/>
     </intent-filter>
   </service>
   

2. ll_push_tracking_activity_enabled to true.

   If you installed SDK 5.5 and up via Maven, Localytics PushTrackingActivity will be included in your manifest. This activity will ensure Push Opened events are tagged.

   If you installed SDK 5.0 - 5.4 via Maven, Localytics PushTrackingActivity should be explicitly declared as exported="false" in your app's manifest. Include the following in your app's manifest:

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

   Otherwise, 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"/>
   

3. ll_default_push_channel_id: Set this value to define the notification channel that push messaging will use if no channel is set in the dashboard.
4. ll_default_push_channel_name: Set this value to define the notification channel's name that push messaging will use if no channel is set in the dashboard. This name will be visible to the end user.
5. ll_default_push_channel_description: Set this value to define the notification channel's description that push messaging will use if no channel is set in the dashboard. This description will be visible to the end user.

If you are using multiple push providers, or prefer to handle push token registration and rendering manually, then set the value of ll_fcm_push_services_enabled to false and refer to Using Custom FCM Services in the advanced section for setup.

4. Register for push notifications in your app

Register for push within onCreate() of your app's MainActivity.

Localytics.registerPush();

Also, make sure that the user's device has the latest version of Google Play Services installed by following our guide for updating Play Services.

5. Add your server API key to the Localytics Dashboard

1. Retrieve your server API key from your Firebase project's settings as shown in the steps in the image below.

   

2. Log in to the Localytics Dashboard, navigate to Settings > Apps, and input your server API key within Add Certs as shown in the steps in the image below.

   

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.

7. Next steps

Since the release of Lollipop (API 21), the material design style dictates that all non-alpha channels in notification icons be ignored. Therefore, depending on the shape of your app icon, your notification icon may not appear as desired on devices running Lollipop or later. To change the notification icon and accent color, use MessagingListener#localyticsWillShowPushNotification to modify the NotificationCompat.Builder to meet your UI needs by following the steps in Modifying push notifications.

Using InboxListAdapter (recommended)

1. Add a ListView and a TextView to be used as the empty view to an Activity or Fragment layout as follows.

   <?xml version="1.0" encoding="utf-8"?>
   <FrameLayout
       xmlns:android="http://schemas.android.com/apk/res/android"
       android:layout_width="match_parent"
       android:layout_height="match_parent">
   
       <ListView
           android:id="@+id/lv_inbox"
           android:layout_width="match_parent"
           android:layout_height="match_parent"
           android:background="@android:color/white"
           android:divider="?android:attr/listDivider"/>
   
       <TextView
           android:id="@+id/tv_empty_inbox"
           android:layout_width="wrap_content"
           android:layout_height="wrap_content"
           android:layout_gravity="center"
           android:text="@string/no_messages"/>
   
   </FrameLayout>
   

2. Set the TextView as the empty view of your ListView and then create an InboxListAdapter and set it as the Adapter of the ListView in your Activity or Fragment as follows.

   Java Kotlin

   @Override
   protected void onCreate(Bundle savedInstanceState) {
   	super.onCreate(savedInstanceState);
   	setContentView(R.layout.activity_inbox);
   		
   	ListView listView = (ListView) findViewById(R.id.lv_inbox);
   	listView.setEmptyView(findViewById(R.id.tv_empty_inbox));
   	InboxListAdapter inboxListAdapter = new InboxListAdapter(this);
   	listView.setAdapter(inboxListAdapter);
   			
   	// ...
   }
   							
   

   override fun onCreate(savedInstanceState: Bundle?) {
   	super.onCreate(savedInstanceState)
   	setContentView(R.layout.activity_inbox)
   			
   	val listView: ListView = findViewById(R.id.lv_inbox) as ListView
   	listView.setEmptyView(findViewById(R.id.tv_empty_inbox))
   			
   	val inboxListAdapter = InboxListAdapter(this)
   	listView.setAdapter(inboxListAdapter)
   	// ...
   }
   							
   

3. Tell the InboxListAdapter to retrieve campaign data as follows. You can optionally include a callback interface to be notified when the refresh has completed.

   Java Kotlin

   @Override
   protected void onCreate(Bundle savedInstanceState) {
   		// ...
   			
   		listView.setAdapter(inboxListAdapter);
   		inboxListAdapter.getData(new InboxListAdapter.Listener() {
   				@Override
   				public void didFinishLoadingCampaigns() {
   						// optionally hide a ProgressBar
   				}
   		});
   			
   		// ...
   }
   							
   

   override fun onCreate(savedInstanceState: Bundle?) { // ...
   	listView.setAdapter(inboxListAdapter)
   	inboxListAdapter.getData(InboxListAdapter.Listener {
   			// optionally hide a ProgressBar
   	})
   	// ...
   }
   							
   

Using your own View

If you prefer to not use InboxListAdapter, you can get inbox data directly via the Localytics class static methods. These methods are useful if you would rather use a RecyclerView or another interface for displaying a list of inbox messages.

To retrieve cached inbox campaign data, call Localytics.getDisplayableInboxCampaigns() from a background thread as follows.

Java Kotlin

new AsyncTask<Void, Void, List<InboxCampaign>>()
{
	@Override
	protected List<InboxCampaign> doInBackground(Void... params) {
		return Localytics.getDisplayableInboxCampaigns();
	}
		
	@Override
	protected void onPostExecute(List<InboxCampaign> campaigns) {
		// create UI using campaigns
	}
}.execute();
					

withContext(Dispatchers.Default) {
	val output = Localytics.getDisplayableInboxCampaigns()
	withContext(Dispatchers.Main) {
		//create UI using campaigns
	}
}

To refresh inbox campaign data from the network, call Localytics.refreshInboxCampaigns(InboxRefreshListener listener) as follows.

Java Kotlin

Localytics.refreshInboxCampaigns(new InboxRefreshListener() {
	@Override
	public void localyticsRefreshedInboxCampaigns(List<InboxCampaign> campaigns) {
		// refresh UI using campaigns
	}
});

Localytics.refreshInboxCampaigns {
	// refresh UI using campaigns
}
					

Changing fonts and color

To change the InboxListItem unread indicator color and text size, color, and font, subclass InboxListAdapter and override getView(int position, View convertView, ViewGroup parent) as follows.

Java Kotlin

public class MyInboxListAdapter extends InboxListAdapter {
		public MyInboxListAdapter(Context context) {
				super(context);
		}
		
		@Override
		public View getView(int position, View convertView, ViewGroup parent) {
				InboxListItem item;
				if (convertView == null) {
						item = new InboxListItem(getContext());
		
						// customize TextViews and UnreadIndicatorView
						item.getTitleTextView().setTextSize(TypedValue.COMPLEX_UNIT_SP, 16);
						item.getSummaryTextView().setTextColor(ContextCompat.getColor(getContext(), R.color.text_color));
						item.getUnreadIndicatorView().setColor(ContextCompat.getColor(getContext(), R.color.unread_color));
				} else {
						item = (InboxListItem) convertView;
				}
		
				item.populateViews(getItem(position), true);
		
				return item;
		}
}

open class MyInboxListAdapter : InboxListAdapter(context: Context) {
	override fun getView(position: Int, convertView: View, parent: ViewGroup): View {
		var item: InboxListItem
		if (convertView == null) {
			item = InboxListItem(getContext())

			// customize TextViews and UnreadIndicatorView
			item.getTitleTextView().setTextSize(TypedValue.COMPLEX_UNIT_SP, 16)
			item.getSummaryTextView().setTextColor(ContextCompat.getColor(getContext(), R.color.text_color))
			item.getUnreadIndicatorView().setColor(ContextCompat.getColor(getContext(), R.color.unread_color))
		} else {
			item = convertView as InboxListItem
		}

		item.populateViews(getItem(position), true)

		return item
	}
}

Manually managing thumbnails

To manually manage InboxListItem thumbnail downloading and caching, subclass InboxListAdapter and disable thumbnail downloading before you add it to the ListView. Next, override getView(int position, View convertView, ViewGroup parent) to handle thumbnail images as follows.

Java Kotlin

@Override
protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		setContentView(R.layout.activity_inbox);
		
		ListView listView = (ListView) findViewById(R.id.lv_inbox);
		MyInboxListAdapter inboxListAdapter = new MyInboxListAdapter(this);
		inboxListAdapter.setDownloadsThumbnails(false);
		listView.setAdapter(inboxListAdapter);
		
		// ...
}

public class MyInboxListAdapter extends InboxListAdapter {
		public MyInboxListAdapter(Context context) {
				super(context);
		}
		
		@Override
		public View getView(int position, View convertView, ViewGroup parent) {
				if (convertView == null) {
						convertView = new InboxListItem(getContext());
				}
		
				InboxListItem item = (InboxListItem) convertView;
				InboxCampaign campaign = getItem(position);
				item.populateViews(campaign, false);
		
				ImageView thumbnailImageView = item.getThumbnailImageView();
				if (campaign.hasThumbnail()) {
						thumbnailImageView.setVisibility(View.VISIBLE);
						Uri thumbnailUri = campaign.getThumbnailUri();
						// load thumbnail URI into ImageView
				} else {
						thumbnailImageView.setImageURI(null);
						thumbnailImageView.setVisibility(View.GONE);
				}
		
				return item;
		}
}

override fun onCreate(savedInstanceState: Bundle?) {
	super.onCreate(savedInstanceState)
	setContentView(R.layout.activity_inbox)

	val listView: ListView = findViewById(R.id.lv_inbox) as ListView
	val inboxListAdapter = MyInboxListAdapter(this)

	inboxListAdapter.setDownloadsThumbnails(false)
	listView.setAdapter(inboxListAdapter)
	// ...
}

open class MyInboxListAdapter : InboxListAdapter(context: Context) {		
	override fun getView(position: Int, convertView: View?, parent: ViewGroup?): View? {
		var convertView = convertView
		if (convertView == null) {
			convertView = InboxListItem(getContext())
		}
		val item = convertView as InboxListItem
		val campaign: InboxCampaign = getItem(position)

		item.populateViews(campaign, false)
		val thumbnailImageView: ImageView = item.thumbnailImageView
		if (campaign.hasThumbnail()) {
			thumbnailImageView.setVisibility(View.VISIBLE)
			val thumbnailUri: Uri? = campaign.thumbnailUri
			// load thumbnail URI into ImageView
		} else {
			thumbnailImageView.setImageURI(null)
			thumbnailImageView.setVisibility(View.GONE)
		}
		return item
	}
}

Using a custom list item view

To use your own inflated view within InboxListAdapter, subclass InboxListAdapter and disable thumbnail downloading before you add it to the ListView. Next, override getView(int position, View convertView, ViewGroup parent) to inflate and populate your own view as follows.

Java Kotlin

@Override
protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		setContentView(R.layout.activity_inbox);
		
		ListView listView = (ListView) findViewById(R.id.lv_inbox);
		MyInboxListAdapter inboxListAdapter = new MyInboxListAdapter(this);
		inboxListAdapter.setDownloadsThumbnails(false);
		listView.setAdapter(inboxListAdapter);
		
		// ...
}

public class MyInboxListAdapter extends InboxListAdapter {
		public MyInboxListAdapter(Context context) {
				super(context);
		}
		
		@Override
		public View getView(int position, View convertView, ViewGroup parent) {
				if (convertView == null) {
						LayoutInflater inflater = (LayoutInflater) getContext()
										.getSystemService(Context.LAYOUT_INFLATER_SERVICE);
						convertView = inflater.inflate(R.layout.item_inbox, parent, false);
						convertView.setTag(new ViewHolder(convertView));
				}
		
				ViewHolder holder = (ViewHolder) convertView.getTag();
				InboxCampaign campaign = getItem(position);
		
				holder.title.setText(campaign.getTitle());
				holder.summary.setText(campaign.getSummary());
		
				return convertView;
		}
		
		static class ViewHolder {
				TextView title;
				TextView summary;
		
				public ViewHolder(View view) {
						title = (TextView) view.findViewById(R.id.tv_title);
						summary = (TextView) view.findViewById(R.id.tv_summary);
				}
		}
}

override fun onCreate(savedInstanceState: Bundle?) {
	super.onCreate(savedInstanceState)
	setContentView(R.layout.activity_inbox)
	val listView: ListView = findViewById(R.id.lv_inbox) as ListView
	val inboxListAdapter = MyInboxListAdapter(this)
	inboxListAdapter.setDownloadsThumbnails(false)
	listView.setAdapter(inboxListAdapter)
	// ...
}
					

open class MyInboxListAdapter : InboxListAdapter(context: Context) {			
	override fun getView(position: Int, convertView: View?, parent: ViewGroup?): View? {
		var convertView = convertView
		if (convertView == null) {
				val inflater = context.getSystemService(Context.LAYOUT_INFLATER_SERVICE) as LayoutInflater
				convertView = inflater.inflate(R.layout.item_inbox, parent, false)
				convertView!!.tag = ViewHolder(convertView)
		}
		val holder: ViewHolder = convertView.tag as ViewHolder
		val campaign: InboxCampaign = getItem(position)
		holder.title.setText(campaign.title)
		holder.summary.setText(campaign.summary)
		return convertView
	}

	internal class ViewHolder(view: View) {
		var title: TextView
		var summary: TextView
				
		init {
			title = view.findViewById<View>(R.id.tv_title) as TextView
			summary = view.findViewById<View>(R.id.tv_summary) as TextView
		}
	}
}
					

Handling message detail errors

If you are using the v3 version of the Localytics SDK, follow our guide for Handling detail message errors in v3 in the Legacy SDKs section.

In rare cases the inbox message detail view may fail to load. By default, InboxDetailFragment will display a gray "X" in the center of the view when this occurs. To provide your own custom error view, implement the InboxDetailCallback interface in the attached Activity as follows.

Java Kotlin

public class MyInboxActivity extends Activity implements InboxDetailCallback
{
	@Override
	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		setContentView(R.layout.activity_inbox_campaign);
		
		if (savedInstanceState == null) {
				InboxCampaign campaign = getIntent().getParcelableExtra("campaign");
				InboxDetailFragment fragment = InboxDetailFragment.newInstance(campaign);
				getFragmentManager().beginTransaction()
								.add(R.id.container, fragment)
								.commit();
		}
	}
		
	@Override
	public void onCreativeLoadError() {
		findViewById(R.id.error_view).setVisibility(View.VISIBLE);
	}
}
					

class MyInboxActivity : Activity(), InboxDetailCallback {
	override fun onCreate(savedInstanceState: Bundle?) {
		super.onCreate(savedInstanceState)
		setContentView(R.layout.activity_inbox_campaign)
		if (savedInstanceState == null) {
				val campaign: InboxCampaign = intent.getParcelableExtra("campaign")
				val fragment = InboxDetailFragment.newInstance(campaign)
				fragmentManager.beginTransaction()
						.add(R.id.container, fragment)
						.commit()
		}
	}

	override fun onCreativeLoadError() {
		findViewById(R.id.error_view).setVisibility(View.VISIBLE)
	}
}

Deleting Inbox Campaigns (SDK v5.2+)

Starting in SDK v5.2 Inbox campaigns can be deleted. To delete an Inbox Campaign, you can call either of the following methods:

Localytics.deleteInboxCampaign(InboxCampaign campaign);
((InboxCampaign) campaign).delete();

Any deleted inbox campaign will not be considered displayable. As a result they will be excluded from the list of campaigns retrieved by calling getDisplayableInboxCampaigns, getInboxCampaigns and refreshInboxCampaigns. Additionally, they will be excluded from the count returned by getInboxCampaignsUnreadCount.

If you need the list of deleted Inbox campaigns, you can call Localytics.getAllInboxCampaigns() or Localytics.refreshAllInboxCampaigns() and filter for campaigns with the property deleted set to true.

Additionally, if you are using the Localytics provided inbox view, swiping to delete an item can be enabled by passing the ListView as an additional parameter to the InboxListAdapter.

Java Kotlin

@Override
protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		setContentView(R.layout.activity_inbox);
		
		ListView listView = (ListView) findViewById(R.id.lv_inbox);
		listView.setOnItemClickListener(this);
		InboxListAdapter inboxListAdapter = new InboxListAdapter(this, listView);
		listView.setAdapter(inboxListAdapter);
		inboxListAdapter.getData(null);
}
					

override fun onCreate(savedInstanceState: Bundle?) {
	super.onCreate(savedInstanceState)
	setContentView(R.layout.activity_inbox)
	
	val listView: ListView = findViewById(R.id.lv_inbox) as ListView
	listView.setOnItemClickListener(this)
	val inboxListAdapter = InboxListAdapter(this, listView)
	listView.setAdapter(inboxListAdapter)
	inboxListAdapter.getData(null)
}
					

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:

Localytics.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:

Java Kotlin

//Code from Application class
@Override
public void onCreate() {
  super.onCreate();
    
  Localytics.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()) {
    Localytics.setOptedOut(true);
  }
}
          

// Code from Application class
override fun onCreate() {
  super.onCreate()
  Localytics.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()) {
    Localytics.setOptedOut(true)
  }
}

This effectively suppresses the integration until consent is verified.

Methods to support GDPR and other privacy requirements

The Localytics SDK provides the following APIs in SDK v5.1+:

• Localytics.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, cease data collection, and have all of their historical data deleted. For additional details, please refer to this help document
• Localytics.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.
• Localytics.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.

Localytics.pauseDataUploading(true);
Localytics.autoIntegrate(this);
HandlerThread thread = new HandlerThread("opt-out-check", android.os.Process.THREAD_PRIORITY_BACKGROUND);
thread.start();
new android.os.Handler(thread.getLooper()).post(new Runnable() {
  @Override
  public void run() {
    //This will be available even when the end user is opted out.
    String customerId = Localytics.getCustomerId();
    //Make a request to your servers to see if the end user is opted out.
    boolean isUserOptedOutOnServer;
    Localytics.setPrivacyOptedOut(isUserOptedOutOnServer);
    Localytics.pauseDataUploading(false);
  }
}
            

Localytics.pauseDataUploading(true)
Localytics.autoIntegrate(this)
runBlocking {
  val customerId: String = Localytics.getCustomerId()
  val isUserOptedOutOnServer: Boolean = // Make a request to your servers to see if the end user is opted out.
  Localytics.setPrivacyOptedOut(isUserOptedOutOnServer)
  Localytics.pauseDataUploading(false)
}
            

Localytics.pauseDataUploading(true);
HandlerThread thread = new HandlerThread("opt-out-check", android.os.Process.THREAD_PRIORITY_BACKGROUND);
thread.start();
new android.os.Handler(thread.getLooper()).post(new Runnable() {
  @Override
  public void run() {
    //Make a request to your servers to retrieve the end user's customer id and opted out status.
    String customerIdFromServer;
    boolean isUserOptedOutOnServer;
    Localytics.setCustomerIdWithPrivacyOptedOut(customerIdFromServer, isUserOptedOutOnServer);
    Localytics.pauseDataUploading(false);
  }
}
            

Localytics.pauseDataUploading(true)
runBlocking {
  val customerId: String = Localytics.getCustomerId()
  val isUserOptedOutOnServer: Boolean = // Make a request to your servers to see if the end user is opted out.
  Localytics.setPrivacyOptedOut(isUserOptedOutOnServer)
  Localytics.pauseDataUploading(false)
}
            

Localytics.setCustomerIdWithPrivacyOptedOut(null, false);

Analytics callbacks

These analytics callbacks are useful for setting the value of a custom dimension or profile attribute before a session opens, 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 your Application class implement the AnalyticsListener interface as follows.

Java Kotlin

public class MyApplication extends Application implements AnalyticsListener {
    
  @Override
  public void onCreate() {
    super.onCreate();
    
    Localytics.autoIntegrate(this);
    Localytics.setAnalyticsListener(this);
  }
    
  @Override
  public void localyticsSessionWillOpen(boolean isFirst, boolean isUpgrade, boolean isResume) {
    // ... do something ...
  }
    
  @Override
  public void localyticsSessionDidOpen(boolean isFirst, boolean isUpgrade, boolean isResume) {
    // ... do something ...
  }
    
  @Override
  public void localyticsSessionWillClose() {
    // ... do something ...
  }
    
  @Override
  public void localyticsDidTagEvent(String eventName, Map<String, String> attributes, long customerValueIncrease) {
    // ... do something ...
  }
}