iOS SDK Weex Framework Support

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

**The latest version is **: 2.0.0

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

I. Integrate SDK

1.1 Integration iOS SDK and Weex support files

(1) Integration iOS SDK See iOS SDK User Guide

(2) After completing the integration of the iOS SDK, please click here to download (opens new window)the Weex support file, unzip the WeexThinkingDataAnalyticsModule.hand WeexThinkingDataAnalyticsModule.mfiles to add to your project.

In addition, the print data log can be turned on by calling the setLogLevelmethod.

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.

iOS SDK Since v2.3.0, the SDK can configure HTTPS validation methods.

iOS SDK supports setting default time zones since v2.3.1, which can be configured as needed.

iOS SDK Since v2.4.0, the client side SDK supports Debug mode.

See iOS SDK User Guide

(3) Add in AppDelegate.m Add in AppDelegate.m

#import "WeexThinkingDataAnalyticsModule.h"

Then in the application: didFinishLaunchingWithOptions:method, after iOS SDK and Weex initialization code, add the Weex support plug-in initialization code

-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Initialise iOS SDK
    [ThinkingAnalyticsSDK startWithAppId:@"APP_ID"
                                   withUrl:@"SERVER_URL"];
    // Initialise weex
    [WeexSDKManager setup];
    // Initialise the Weex support plug-in
    [WXSDKEngine registerModule:@"WeexThinkingDataAnalyticsModule" withClass:[WeexThinkingDataAnalyticsModule class]];
    return YES;
}

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)

The SDK instance will use random UUID as the default guest ID for each user, which will be used as the user identification ID when the user is not logged in. It should be noted that the guest ID will change when the user reinstates the app and changes the device.

If the user can be used in your product without logging in, and you need to configure the user's guest ID in the unlogged state, you can call identifyto set it up:

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 called logout. It has been retained until:

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.

If you call the login interface in the iOS SDK and set the account ID, the call in the RN will overwrite the previously set account ID, and the same iOS subsequent login calls in the SDK will also overwrite the account ID set by the RN.

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

2.3 Clear Account ID

After the user generates 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" });

The call to logout in the RN will also clear the account ID in the iOS SDK, and the same iOS SDK call to logout will also clear the account ID in the RN.

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

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

EventNameis the event name of the event, and the propertiesare all attributes of the event. In the iOS SDK v2.2.0 version, the method overloading of 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 only receive 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 whole data cannot be stored.

Since iOS SDK v2.3.1, you can align event times in multiple time zones by setting the SDK default time zone. Please refer to the iOS SDK User Guide Setting the Default Time Zone section. Since iOS 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. Public event properties refer to the properties that each event will carry. You can call setSuperPropertiesto set public properties. We recommend that you set public event properties before sending events.

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 the #durationattribute to 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 RN can record corresponding events uploaded iOS SDK, and the timing set iOS SDK can record corresponding events uploaded in 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 incoming attribute

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

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, this information will be ignored.

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

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

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

4.4 UserUnset

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

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

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 iOS 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

Refer to the chapter iOS 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 iOS SDK v2.1.0 version, the function of stopping SDK reporting data has been added. There are two types of interfaces that stop SDK reporting:

6.1.1 Pause SDK Reporting (enableTracking)

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

You can call enableTrackingthrough an instance (including the main instance and the light instance), pass in falseto suspend the reporting of the SDK. The #distinct_id, #account_id, 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, cannot set visitor ID, account ID, and public attributes, etc., but 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 paused state of the light instance will not be retained, and the reporting will be reopened.

// Pause Reporting
tamodal.enableTracking({
  appID: "YOUR_APPID",
  enableTracking: false
});

// Revocer 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 functions of the SDK. For example, in areas where GDPR is applicable, users choose not to provide data collection permissions, you can call the following interface to completely turn off the functions of the SDK.

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 the 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 iOS 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 to the specified 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 the 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, in iOS 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.

Note: Aligning the event time with the specified time zone will lose the device native time zone information. If you need to retain the device native time zone information, you currently need to add relevant attributes for the event yourself.

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