Flutter Tenjin SDK

Pub Version ISC License

A Flutter plugin to Tenjin SDK

โš™๏ธ Installation

Tenjin Docs

  1. Add the dependency to the pubspec.yaml file in your project:
dependencies:
  tenjin_Sdk: any
  1. Install the plugin by running the command below in the terminal, in your project's root directory:
$ flutter pub get

Android

Manifest requirements:

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

If you havenโ€™t already installed the Google Play Services, add it to our build.gradle file. Starting with Tenjin Android SDK v1.8.3, you will need to add Google's Install Referrer Library.

dependencies {
  implementation 'com.google.android.gms:play-services-analytics:17.0.0'
  implementation 'com.android.installreferrer:installreferrer:1.1.2'
}

๐Ÿ“ฑ Usage

Initialization

Get your API_KEY from your Tenjin Organization tab. You can initialize Tenjin with the function

TenjinSDK.instance.init(apiKey: '<API-KEY>');

You can verify if the integration is working through our Live Test Device Data Tool. Add your advertising_id or IDFA/GAID to the list of test devices. You can find this under Support -> Test Devices. Go to the SDK Live page and send a test events from your app. You should see a live event come in:

๐Ÿ‘ฎ๐Ÿพโ€โ™‚๏ธ GDPR compliance

Since iOS 14+ you are required to request a specific permission before you can have access to Apple's IDFA (a sort of proprietary cookie used by Apple to track users among multiple advertisers. To request this permission call the function TenjinSDK.instance.requestTrackingAuthorization():

<key>NSUserTrackingUsageDescription</key>
<string></string>

As part of GDPR compliance, with Tenjin's SDK you can opt-in, opt-out devices/users, or select which specific device-related params to opt-in or opt-out. OptOut() will not send any API requests to Tenjin and we will not process any events.

TenjinSDK.instance.init(apiKey: '<API-KEY>');

bool userOptIn = checkOptInValue();

if (userOptIn) {
    TenjinSDK.instance.optIn();
} else {
    TenjinSDK.instance.optOut();
}

TenjinSDK.instance.connect();

To opt-in/opt-out specific device-related parameters, you can use the OptInParams() or OptOutParams(). OptInParams() will only send device-related parameters that are specified. OptOutParams() will send all device-related parameters except ones that are specified. Please note that we require at least ip_address, advertising_id, developer_device_id, limit_ad_tracking, referrer (Android), and iad (iOS) to properly track devices in Tenjin's system. If you plan on using Google, you will also need to add: platform, os_version, locale, device_model, and build_id.

If you want to only get specific device-related parameters, use OptInParams(). In example below, we will only these device-related parameters: ip_address, advertising_id, developer_device_id, limit_ad_tracking, referrer, and iad:

TenjinSDK.instance.init(apiKey: '<API-KEY>');

List<String> optInParams = {"ip_address", "advertising_id", "developer_device_id", "limit_ad_tracking", "referrer", "iad"};
TenjinSDK.instance.optInParams(optInParams);

TenjinSDK.instance.connect();

If you want to send ALL parameters except specfic device-related parameters, use OptOutParams(). In example below, we will send ALL device-related parameters except:

TenjinSDK.instance.init(apiKey: '<API-KEY>');

List<String> optOutParams = {"locale", "timezone", "build_id"};
TenjinSDK.instance.optOutParams(optOutParams);

TenjinSDK.instance.connect();
ParamDescriptionReference
ip_addressIP Address
advertising_idDevice Advertising IDAndroid
limit_ad_trackinglimit ad tracking enabledAndroid
platformplatformAndroid
referrerGoogle Play Install ReferrerAndroid
os_versionoperating system versionAndroid
devicedevice nameAndroid
device_manufacturerdevice manufactuerAndroid
device_modeldevice modelAndroid
device_branddevice brandAndroid
device_productdevice productAndroid
carrierphone carrierAndroid
connection_typecellular or wifiAndroid
screen_widthdevice screen widthAndroid
screen_heightdevice screen heightAndroid
os_version_releaseoperating system versionAndroid
build_idbuild IDAndroid
localedevice localeAndroid
countrylocale countryAndroid
timezonetimezoneAndroid

๐Ÿ’ต Purchase Event

To understand user revenue and purchase behavior, developers can send transaction events to Tenjin. There are two ways to send transaction events to Tenjin.

Validate receipts

Tenjin can validate transaction receipts for you.

Dashboard

Example:

TenjinSDK.instance.transaction(
  ...
);

You can verify if the IAP validation is working through our Live Test Device Data Tool. You should see a live event come in:

Custom Event

NOTE: DO NOT SEND CUSTOM EVENTS BEFORE THE INITIALIZATION connect() event (above). The initialization event must come before any custom events are sent.

IMPORTANT: Limit custom event names to less than 80 characters. Do not exceed 500 unique custom event names.

You can use the Tenjin SDK to pass a custom event: eventWithName(String name).

The custom interactions with your app can be tied to level cost from each acquisition source that you use through Tenjin's service. Here is an example of usage:

//Integrate a custom event with a distinct name - ie. swiping right on the screen
TenjinSDK.instance.eventWithName("swipe_right");

Passing custom events with integer values:

To pass a custom event with an integer value: eventWithNameAndValue(String name, String value) or eventWithNameAndValue(String name, int value).

Passing an integer value with an event's name allows marketers to sum up and track averages of the values passed for that metric in the Tenjin dashboard. If you plan to use DataVault, these values can be used to derive additional metrics that can be useful.

TenjinSDK.instance.eventWithNameAndValue("item", 100);

Using the example above, the Tenjin dashboard will sum and average the values for all events with the name item.

Keep in mind that this event will not work if the value passed is not an integer.


Tenjin supports the ability to direct users to a specific part of your app after a new attributed install via Tenjin's campaign tracking URLs. You can utilize the getDeeplink method and callback to access the deferred deeplink through the data object. To test you can follow the instructions found here

TenjinSDK.instance.setRewardCallback = (bool clickedTenjinLink,
        bool isFirstSession, Map<String, String> data) {
      if (isFirstSession) {
        if (clickedTenjinLink) {
          if (data.containsKey(TenjinSDK.DEEPLINK_URL)) {
            // use the deferred_deeplink_url to direct the user to a specific part of your app
          }
        }
      }
    };

Below are the parameters, if available, that are returned in the deferred deeplink callback:

ParameterDescription
advertising_idAdvertising ID of the device
ad_networkAd network of the campaign
campaign_idTenjin campaign ID
campaign_nameTenjin campaign name
site_idSite ID of source app
referrerThe referrer params from the app store
deferred_deeplink_urlThe deferred deep-link of the campaign
clickedTenjinLinkBoolean representing if the device was tracked by Tenjin
isFirstSessionBoolean representing if this is the first session for the device

You can also use the v1.7.1+ SDK for handling post-install logic by checking the isFirstSession param. For example, if you have a paid app, you can register your paid app install in the following way:

TenjinSDK.instance.init(apiKey: '<API-KEY>');
TenjinSDK.instance.setRewardCallback = (bool clickedTenjinLink,
        bool isFirstSession, Map<String, String> data) {
      if (isFirstSession) {
          // send paid app price and revenue to Tenjin
      }
    };

App Subversion parameter for A/B Testing (requires DataVault)

If you are running A/B tests and want to report the differences, we can append a numeric value to your app version using the appendAppSubversion method. For example, if your app version 1.0.1, and set appendAppSubversion: @8888, it will report as 1.0.1.8888.

This data will appear within DataVault where you will be able to run reports using the app subversion values.

TenjinSDK.instance.init(apiKey: '<API-KEY>');
TenjinSDK.instance.appendAppSubversion(8888);
TenjinSDK.instance.connect();

ProGuard Settings:

-keep class com.tenjin.** { *; }
-keep public class com.google.android.gms.ads.identifier.** { *; }
-keep public class com.google.android.gms.common.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep class * extends java.util.ListResourceBundle {
    protected Object[][] getContents();
}
-keepattributes *Annotation*

๐Ÿ“ License

Tenjin is released under the ISC License. See LICENSE for details.

๐Ÿ‘จ๐Ÿพโ€๐Ÿ’ป Author

Giovani Lobato (GitHub)

Libraries

tenjin_sdk