ReactNative SDK User Guide

This guide will show you how to use the features of the SDK in React Native.

**The latest version is **: 2.1.2

**Updated **: 2021-04-16

I. Integrate SDK

React-neutral-thinking-data has two integration methods: automatic and manual, automatic integration is recommended.

1.1 Automatic Integration

1.Npm install react-native-thinking-data module

npm install react-native-thinking-data --save

2. link react-native-thinking-data Module

react-native link react-native-thinking-data（React Native version below 0.60）
cd ios&&pod install（React Native version above 0.60）

1.2 Manual Integration

1.Npm install react-native-thinking-data module

npm install react-native-thinking-data --save

2. Android & iOS platform configuration

• iOS

1. In XCode, in the project navigator, right click Libraries ➜ Add Files to [your project's name]
2. Go to node_modules ➜ react-native-thinking-data and add RNThinkingData.xcodeproj
3. In XCode, in the project navigator, select your project. Add libRNThinkingData.a to your project's Build Phases ➜ Link Binary With Libraries
4. Run your project (Cmd+R)

• Android

5. Open up android/app/src/main/java/[...]/MainActivity.java

• Add import cn.thinking.RNThinkingDataPackage; to the imports at the top of the file
• Add new RNThinkingDataPackage() to the list returned by the getPackages() method

6. Append the following lines to android/settings.gradle:

include ':react-native-thinking-data'
project(':react-native-thinking-data').projectDir = new File(rootProject.projectDir,     '../node_modules/react-native-thinking-data/android')

7. Insert the following lines inside the dependencies block in android/app/build.gradle:

compile project(':react-native-thinking-data')

Use SDK-related features in ReactNative after importing

II. Set User ID

2.1 Set Visitor ID (optional)

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

RNThinkingAnalyticsModule.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. Keep it until:

RNThinkingAnalyticsModule.login({ appid: "YOUR_APPID", loginId: "account_id" });

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:

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

RNThinkingAnalyticsModule.track({
  appid: "YOUR_APPID",
  eventName: "rn_texttrack"
});

RNThinkingAnalyticsModule.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().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, which 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.

RNThinkingAnalyticsModule.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

RNThinkingAnalyticsModule.unsetSuperProperty({
  appid: "YOUR_APPID",
  properties: "superKey"
});

RNThinkingAnalyticsModule.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.

RNThinkingAnalyticsModule.timeEvent({
  appid: "YOUR_APPID",
  eventName: "track"
});

The incoming 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 properties uploaded using this interface will overwrite the original property 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 property. Take setting the user name as an example:

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

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

RNThinkingAnalyticsModule.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

RNThinkingAnalyticsModule.userUnset({
  appid: "YOUR_APPID",
  properties: "usersetkey"
});

The parameter passed in by userUnset is the property name of the user feature. 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.

RNThinkingAnalyticsModule.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.

RNThinkingAnalyticsModule.userAppend({
  appid: "YOUR_APPID",
  properties: { key: ["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

For details on how to use automatic collection events, please refer to the chapter of the Android SDK Automatic Collection Guide .

The call method in RN is as follows:

RNThinkingAnalyticsModule.enableAutoTrack({
  appid: "YOUR_APPID",
  autoTrackType: {
    appStart: true,
    appEnd: true,
    appViewCrash: 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), pass in falseto suspend the reporting of the SDK instance. 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 the 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.

RNThinkingAnalyticsModule.enableTracking({
  appid: "YOUR_APPID",
  enableTracking: true
});
RNThinkingAnalyticsModule.enableTracking({
  appid: "YOUR_APPID",
  enableTracking: false
});

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, and 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.

RNThinkingAnalyticsModule.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.

RNThinkingAnalyticsModule.optOutTrackingAndDeleteUser({ appid: "YOUR_APPID" });

The stopped 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 completely new instance

RNThinkingAnalyticsModule.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
RNThinkingAnalyticsModule.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
RNThinkingAnalyticsModule.calibrateTimeWithNtp({
  ntp_server: "time.apple.com"
});

Note:

• You need to choose your NTP server address carefully to ensure that when the network is in good condition, the user equipment can get the server time quickly.
• 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.

VII. Advanced Functions

Starting with v2.1.0, the SDK supports the reporting of three special types of events: first-time events, updatable events, and rewritable events. These three events need to be used in conjunction with TA system 2.8 and later versions. Since special events are only applicable in certain specific scenarios, please use special events to report data with the help of Count Technology's customer success and analysts.

7.1 First Incident

First-time events are events that are recorded only once for an ID of a device or another dimension. For example, in some scenarios, you may want to record the first event on a device, so you can use first-time events to report data.

// Instance: Report device first event, assuming event name is DEVICE_ FIRST
RNThinkingAnalyticsModule.trackFirstEvent({
  appid: "YOUR_APPID",
  eventName: "DEVICE_FIRST",
  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"
  }
});

If you want to determine whether it is the first time in a dimension other than the device, you can set FIRST_CHECK_ID for the first event. For example, if you need to record the first event of an account, you can set the account ID to the FIRST_CHECK_ID of the first event:

// Instance：First event to report a user account, assuming the event name is USER_ FIRST
RNThinkingAnalyticsModule.trackFirstEvent({
  appid: "YOUR_APPID",
  eventName: "DEVICE_FIRST",
  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"
  },
  eventId: "YOUR_ACCOUNT_ID"
});

Note: Due to the completion of the verification of whether it is the first time at the server level, the first event will be delayed by 1 hour by default.

7.2 Updatable Events

You can implement the requirement to modify event data in a specific scenario through updatable events. Updatable events need to specify an ID that identifies the event and pass it in when the updatable event object is created. The TA background will determine the data that needs to be updated based on the event name and event ID.

// Instance: Report an event that can be updated, assuming the event name is UPDATABLE_ EVENT
RNThinkingAnalyticsModule.trackUpdate({
  appid: "YOUR_APPID",
  eventName: "UPDATABLE_EVENT",
  properties: { status: 3, price: 100 },
  eventId: "test_event_id",
});
// Event attributes after reporting are status 3 and price 100
RNThinkingAnalyticsModule.trackUpdate({
  appid: "YOUR_APPID",
  eventName: "UPDATABLE_EVENT",
  properties: { status: 5 },
  eventId: "test_event_id",
});

Updatable events will update the event time of historical data by default using the current time of the device. If you want to specify the event time, you can specify the event time when reporting the updatable event:

RNThinkingAnalyticsModule.trackUpdate({
  appid: "YOUR_APPID",
  eventName: "OVERWRITE_EVENT",
  eventId: "test_event_id",
  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().getTime(),
  timeZone: "UTC",
});

7.3 Rewritable Events

Rewritable events are similar to updatable events, except that rewritable events will completely cover historical data with the latest data, which is equivalent to deleting the previous data and storing the latest data in effect. The TA background will determine the data that needs to be updated based on the event name and event ID.

// Instance: Report an event that can be overridden, assuming the event name is OVERWRITE_ EVENT
RNThinkingAnalyticsModule.trackOverwrite({
  appid: "YOUR_APPID",
  eventName: "OVERWRITE_EVENT",
  properties: { status: 3, price: 100 },
  eventId: "test_event_id",
});

// Event attributes after reporting are status 3 and price 100
RNThinkingAnalyticsModule.trackOverwrite({
  appid: "YOUR_APPID",
  eventName: "OVERWRITE_EVENT",
  properties: { status: 5 },
  eventId: "test_event_id",
});
// Event attributes status is updated to 5 and price attributes are deleted after reporting

Rewritable events will overwrite the event time of historical data by default using the current time of the device. If you want to specify the event time, you can specify the event time when reporting the rewritable event:

RNThinkingAnalyticsModule.trackOverwrite({
  appid: "YOUR_APPID",
  eventName: "OVERWRITE_EVENT",
  properties: { status: 5 },
  eventId: "test_event_id",
  time: new Date().getTime(),
  timeZone: "UTC",
});

ChangeLog

v2.1.2 2021/03/16

• Adaptation iOS 14
• Adapt to Android 11
• Added preset property #bundle_id (apply unique identification)
• Optimizing network signal acquisition logic

v2.1.1 2020/10/29

• Adapt iOS 5G network
• Optimize install, start event reporting logic
• Optimized data transfer format
• Default network reporting policy adjusted to 2G/3G/4G/5G/WIFI

v2.1.0 2020/08/27

• Add trackUpdate, trackOverwrite, trackFirstEvent interface

v2.0.1 2020/06/05

• Supports JSONArray types

v2.0.0 2020/05/25

• 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