# Android SDK Weex Framework Support

This guide will show you how to use the features of the Android SDK in Weex.

**The latest version is **: 2.0.0

**Update time is **: 2020-06-06

# I. Integrate SDK

# 1.1 Integrate Android SDK with Weex Support Files

Integrating the Android SDK See the Android SDK Usage Guide

After completing the Android SDK integration, please click here to download (opens new window)the Weex support file, unzip and add the WeexThinkingData AnalyticsM odule.javafile to your project.

After the file is added, add the WeexThinkingDataAnalyticsModule module to the onCreate method of the Application.

 try {
      WXSDKEngine.registerModule("WeexThinkingDataAnalyticsModule", WeexThinkingDataAnalyticsModule.class);
    } catch (WXException e) {
      e.printStackTrace();
    }

In addition, the Android SDK can modify some global settings through the AndroidM anifest.xml. In general, the default settings can be used. Log function can be turned on.

Set the network conditions for uploading. By default, the SDK will upload data in 3G, 4G and Wifi. You can modify the network conditions that allow uploading through the setNetworkTypemethod.

Android SDK since v2.3.0 version, SDK can be set from the visa book.

Android SDK Since v2.3.0, the client side SDK supports Debug mode.

Since v2.3.1, the Android SDK supports setting default time zones, which can be configured as needed.

See Android SDK Usage Guide

# 1.2 Get Modules in JS Files

Please add the following code to the specific JS file you use:

var tamodal = weex.requireModule("WeexThinkingDataAnalyticsModule");

# 1.3 Using SDK Functionality in Weex

Use SDK functionality in RN after import.

# II. Set User ID

# 2.1 Set Visitor ID (optional)

If your app has its own visitor ID management system for each user, you can call identifyto set the visitor ID:

tamodal.identify({
  appID: "YOUR_APPID",
  distinctId: "distinctId1"
});

# 2.2 Set Account ID

When the user logs in, you can call loginto set the user's account ID. After setting the account ID, the account ID will be used as the identification ID, and the set account ID will be retained until logoutis called:

tamodal.login({
  appID: "YOUR_APPID",
  loginId: "weex_textlogin"
});

Logincan be called many times. Each call will determine whether the incoming account ID is consistent with the previously saved ID. If it is consistent, the call will be ignored, and if it is inconsistent, the previous ID will be overwritten.

Note that this method does not upload events for user logins**.**

# 2.3 Clear Account ID

After the user produces login behavior, you can call logoutto clear the account ID. Before the next call to login, the guest ID will be used as the identification ID:

tamodal.logout({ appID: "YOUR_APPID" });

We recommend that you call logoutduring explicit logout events, such as when the user logs off the account, rather than when the app is closed.

Note that this method does not upload user logged-out events**.**

# III. Send Events

# 3.1 Send Events

You can call trackto upload events. This interface will call the trackinterface in the SDK. For detailed instructions, please refer to the introduction of the trackinterface in the SDK doc:

tamodal.track({
  appID: "YOUR_APPID",
  eventName: "track"
});

tamodal.track({
  appID: "YOUR_APPID",
  eventName: "rn_texttrack",
  properties: {
    KEY_NUMBER: 1.02,
    KEY_STRING: "name",
    KEY_LIST: [1, 2, 3],
    KEY_BOOL: true,
    KEY_DateTime: "2020-05-12 06:27:18.371"
  },
  time: new Date("May 17, 2020 03:24:00").getTime(),
  timeZone: "UTC"
});

Event Nameis the event name of the event, and the propertiesare all attributes of the event. In the Android SDK v2.2.0 version, a method overload for setting the event trigger time and time offset is added. It supports passing in timetype parameters to set the event trigger time, and timeZoneto set the time offset. If this parameter is not passed in, the local time and offset when the trackis called are taken as the event trigger time and time zone offset.

Note: Although the trigger time can be set for the event, the receiving end will make the following restrictions, only receiving data from the first 10 days to the last 3 days relative to the server time. Data exceeding the time limit will be regarded as abnormal data, and the entire data cannot be stored.

Starting with Android SDK v2.3.1, you can align the time of events in multiple time zones by setting the default time zone of the SDK. Please refer to the section on Setting Default Time Zone in the Android SDK User Guide . Starting from Android SDK v2.5.0, you can use server level time to complete data collection by calibrating the SDK time interface. Please refer to the Calibration Time section .

# 3.2 Set Public Event Properties

For some important attributes, such as the user's membership level, source channel, etc., these attributes need to be set in each event. At this time, you can set these attributes as public event attributes. The public event property refers to the property that each event will carry. You can call setSuperPropertiesto set the public event property. We recommend that you set the public event property before sending the event.

Format requirements for public event properties are consistent with event properties.

tamodal.setSuperProperties({
  appID: "YOUR_APPID",
  properties: { superKey: 1, superKey2: "value" }
});

If you need to delete a public event property, you can call unsetSuperPropertyto clear the specified public event property; if you want to empty all public event properties, you can call clearSuperProperties

tamodal.unsetSuperProperty({
  appID: "YOUR_APPID",
  properties: "superKey"
});

tamodal.clearSuperProperties({ appID: "YOUR_APPID" });

# 3.3 Record the Duration of the Event

You can call timeEventto start timing, configure the event type you want to time, and when you upload the event, you will automatically add #durationto your event attribute to indicate the length of the record, in seconds.

tamodal.timeEvent({
  appID: "YOUR_APPID",
  eventName: "rn_texttrack"
});

The passed parameter is the event name of the event that needs to record the time. When the event is triggered, the timing will stop, and the timing attribute of #durationwill be recorded in the event.

The timing set in the RN can record the corresponding events uploaded by the Android SDK, and the timing set by the Android SDK can record the corresponding events uploaded in the RN.

# IV. User Attributes

TA platform currently supports the user feature setting interface for userSet, userSetOnce, userAdd, userUnset, userDeland userAppend

# 4.1 UserSet

For general user features, you can call userSetto set it. The attributes uploaded using this interface will overwrite the original attribute values. If the user feature does not exist before, the new user feature will be created. The type is the same as the type of the passed-in attribute. Take setting the user name as an example:

tamodal.userSet({
  appID: "YOUR_APPID",
  properties: { usersetkey: 2, usersetkey2: "usersetvalue" }
});

The user feature format set by userSet requires consistency with event properties.

# 4.2 UserSetOnce

If the user feature you want to upload only needs to be set once, you can call userSetOnceto set it. When the attribute already has a value before, this information will be ignored. Take setting the first payment time as an example:

tamodal.userSetOnce({
  appID: "YOUR_APPID",
  properties: { name: "yea" }
});

The user feature format set by userSetOnce requires consistency with event properties.

# 4.3 UserAdd

When you want to upload a numeric attribute, you can call userAddto accumulate the attribute. If the attribute has not been set, a value of 0 will be assigned before calculation. Negative values can be passed in, which is equivalent to subtraction operations. Take the accumulated payment amount as an example:

tamodal.userAdd({
  appID: "YOUR_APPID",
  properties: { age: 1 }
});

The property type and key value limits set by userAdd are consistent with userSet, but Value only allows Number type.

# 4.4 UserUnset

When you want to empty the user feature value of the user, you can call userUnsetto empty the specified attribute. If the attribute has not been created in the cluster, the userUnset **will not **create the attribute.

tamodal.userUnset({
  appID: "YOUR_APPID",
  properties: "usersetkey"
});

The parameter passed in by userUnset is the property name of the user feature, and the type is string or string array, which supports the form of variable-length parameters.

# 4.5 UserDel

If you want to delete a user, you can call userDelto delete the user. You will no longer be able to query the user features of the user, but the events generated by the user can still be queried.

tamodal.userDel({ appID: "YOUR_APPID" });

# 4.6 UserAppend

Starting with the Android SDK v2.4.0, you can call userAppendto append user features of type Array.

tamodal.userAppend({
  appID: "YOUR_APPID",
  properties: { keyArr: ["age", "2"] }
});

# V. Automatic Acquisition Events

**Please note that if you want to use the automatic collection function, please integrate the relevant dependencies of the automatic collection function, **click here to see Add Dependency Code

Refer to the chapter Android SDK Auto Capture Guide for details on how to use Auto Capture events.

The call method in RN is as follows:

tamodal.enableAutoTrack({
  appID: "YOUR_APPID",
  autoTrackType: {
    appStart: true,
    appEnd: true,
    appCrash: true,
    appInstall: true
  }
});

# VI. SDK Configuration

# 6.1 Pause/stop Data Reporting

In the Android SDK v2.1.0 version, the function of stopping SDK instance reporting data has been added. There are two types of interfaces to stop SDK instance reporting:

# 6.1.1 Pause SDK Reporting (enableTracking)

You may want to temporarily stop data collection and reporting in some scenarios, such as when the user is in a test environment or when the user logs in to a test account. At this time, you can call the following interfaces to temporarily stop the reporting of SDK instances.

You can call enableTrackingthrough an instance (including the main instance and the light instance) and pass in falseto suspend the reporting of the SDK instance. The #distinct_id, #account_id, and public attributes that have been set by the instance will be retained; the data that has been collected but has not been successfully reported by the instance will continue to try to report; the subsequent instance cannot collect and report any new data, and cannot set visitor ID, account ID, and public attributes, etc., but you can read that the instance has Set the public properties and device ID, guest ID, account ID and other information.

The stop state of the instance will be saved in the local cache until enableTrackingis called, and trueis passed in. The SDK instance will resume data collection and reporting. It should be noted that the light instance is not cached, so every time you open the App, the pause state of the light instance will not be retained, and the reporting will be reopened.

// Suspend reporting
tamodal.enableTracking({
  appID: "YOUR_APPID",
  enableTracking: false
});

// Restore reporting
tamodal.enableTracking({
  appID: "YOUR_APPID",
  enableTracking: true
});

# 6.1.2 Stop SDK Reporting (optOutTracking)

In some special situations, you may need to completely stop the function of the SDK instance. For example, in areas where GDPR is applicable, the user chooses not to provide data collection permissions, you can call the following interface to completely turn off the function of the SDK instance.

OptOutTrackingcan only be called through the main instance. The biggest difference with enableTrackingis that it will empty the local cache of this instance, including the guest ID, account ID, public attributes, and unreported data queues of this instance. Then turn off the collection and reporting functions of this instance.

tamodal.optOutTracking({ appID: "YOUR_APPID" });

If you want to delete the user's user data in the TA cluster while turning off the SDK function, you can call optOutTrackingAndDeleteUser, which will report a piece of userDeldata before stopping the function of the SDK instance to delete the user's user data.

tamodal.optOutTrackingAndDeleteUser({ appID: "YOUR_APPID" });

The stop state of the instance will also be saved in the local cache until optInTrackingis called, and subsequent reports can continue, but this is equivalent to a brand new instance

tamodal.optInTracking({ appID: "YOUR_APPID" });

# 6.2 Calibration Time

The SDK will use the native time as the event occurrence time by default. If the user manually modifies the device time, it will affect your business analysis. Since the Android SDK v2.5.0 version, you can use the current timestamp obtained from the server level. Calibrate the time of the SDK. After that, all calls that do not specify a time, including event data and user feature setting operations, use the calibrated time as the time of occurrence.

// 1585633785954 is the current UNIX time stamp in milliseconds corresponding to Beijing Time 2020-03-31 13:49:45
tamodal.calibrateTime({ timeStampMillis: 1585633785954 });

We also provide the ability to get time-to-SDK calibration from NTP. You need to pass in an NTP server address that your users can access. The SDK then attempts to obtain the current time from the incoming NTP service address and calibrate the SDK time. If the correct return result is not obtained within the default timeout time (3 seconds), the data will be reported using the local time later.

// Time Calibration Using Apple NTP Service
tamodal.calibrateTimeWithNtp({ ntpServer: "time.apple.com" });

Note:

You need to choose your NTP server address carefully to ensure that the user equipment can get the server time quickly when the network is in good condition.
There is some uncertainty in using the NTP service for time calibration. It is recommended that you give priority to using timestamp calibration.

In addition to the above calibration time interface, the Android SDK v2.5.0 provides time function overloading for all user feature interfaces. When you call the user feature related interface, you pass in the Date object, and the system will use the incoming Date object to set the data #timefield.

# ChangeLog

# v2.0.0 2020/06/06

Add API interface
Support multiple instances
Support automatic collection of events (add APP installation events, start events, close events, crash events)
Support time calibration function of client side SDK
Added optOutTracking/optInTracking interface
Added enableTracking interface, you can turn on or off the instance reporting function
Support event and user feature data reporting
Support public event properties

← iOS SDK Weex Framework Support C SDK User Guide →