# Integrated Requirement

## Compliance Explanation

Please note that when integrating SDK products provided by the TrustDecision in the APP of your company:

1.1 According to the user's information protection regulations, before your users start the App for the first time and start collecting information, your company should fully inform the user of the purpose, method, and scope of collecting, using, and sharing the user's personal information with a third party through an interactive interface or design (such as a pop-up window of the privacy policy), and obtain the express consent of the end user.

1.2 To provide business security and risk control services to your company, the TrustDecision SDK will collect, process, and use the identification information IDFA, AndroidID, OAID, MAC address, Wireless IP address, WIFI list, wireless router identification (BSSID, SSID),device type, device model, system type, geographical location(Rough location information, precise location information), login IP address and other device information of the user's device. To ensure compliance with your use of related services, the aforementioned privacy policy should cover the authorization of TrustDecision SDK to provide services and collect, process, and use relevant information. The following terms are for your reference. The specific expression can be determined by your company according to the overall framework and content of your privacy agreement:

<table border="1">
    <tr>
        <td style="background-color:#FAFAFA"><font size="2">TrustDecision SDK: For business security and risk control, our company uses the TrustDecision SDK. The SDK needs to obtain the information of your devices, such as IDFA, AndroidID, OAID, GAID,MAC address, Wireless IP address, WIFI list, wireless router identification (BSSID, SSID),device type, device model, system type, geographical location(Rough location information, precise location information), login IP address, application list, running process, network type,device software version,sensor information(light sensor, gravity sensor, magnetic field sensor, acceleration sensor, gyroscope sensor) and other related device information, for fraud risk identification.</font></td>
    </tr>
</table>

**Privacy Protocol:**  <https://www.trustdecision.com/legal/privacy-policy>

## Environment

|                           | Android                              | iOS                |
| ------------------------- | ------------------------------------ | :----------------- |
| Supported System Versions | Android 5.0 and above                | iOS 17.6 and above with the RN 0.88 SPM example (check the native SDK minimum for your own app) |
| Supported Architectures   | armeabi-v7a, arm64-v8a, x86 | armv7,arm64,x86_64 |

# Integrate

## Install

### Plugin Install

Please execute in your react native project root directory

```shell
  npm install --save react-native-trustdevice
```

### iOS (React Native 0.88.1, Swift Package Manager)

The plugin contains a `Package.swift` that links the React Native bridge to
`TrustDecisionPro` (5.3.3 or later). `TDBehavior` is not included by default.
In an RN 0.88.1
SPM app, install the npm package, then run the RN SPM migration in the host app:

```shell
npx react-native spm add --deintegrate
```

Open the generated Xcode project and build the app. The RN SPM autolinker
discovers this plugin's `Package.swift`; customers do not need to add a second
Swift package for the bridge manually. The fingerprint SDK is declared
in the bridge manifest. Run `npx react-native spm update` after changing native
dependencies. RN 0.88's SPM integration is experimental; use Xcode and Node
versions supported by RN 0.88.1 (Node 22.13+).

The example app keeps a comment-only `ios/Podfile` solely because CLI 20.2
uses that filename to detect an iOS project. It is not a CocoaPods integration.

The legacy `react-native-trustdevice.podspec` remains for existing CocoaPods
hosts. Do not link the SDK through both CocoaPods and SPM in the same target.
The native CocoaPods distribution is no longer maintained, so new iOS projects
should use the SPM path above.

### iOS behavior collection (optional)

Only if your app calls `start`, `stop`, or `collect`, add
`https://github.com/trustdecision/TDBehavior_spm` in Xcode via **File > Add
Package Dependencies...**. Select **Exact Version** `1.5.2` and add the
`TDBehavior` product to the host App target. Do not add it to the plugin's
`Package.swift` or link it a second time through CocoaPods. Fingerprint APIs
such as `getBlackBoxAsync` and `getDeviceInfoAsync` do not require this package.

### Android behavior collection dependency

The plugin does not bundle the Android behavior collection SDK. If behavior
collection is required, add the following dependency to the host application's
`android/app/build.gradle`:

```gradle
dependencies {
    implementation 'com.trustdecision.android:behavior:1.5.1'
}
```

Then rebuild the native application. Adding or removing this dependency cannot
be applied through Metro hot reload.

### Device information and verification UI

`TrustDevice` is the enterprise module (the package's default export), and
`TrustDeviceSe` is the standard module (named export). Both expose
`getDeviceInfo()` and `getDeviceInfoAsync()` as Promise methods returning
`blackBox`, `fpVersion`, `anonymousId`, `deviceRiskScore`, `sealedResult`, and
`apiStatus: {code, message}`. The standard iOS SDK has only a callback API, so
both methods use that asynchronous native call. Call them after initialization.

```javascript
import TrustDevice, {TrustDeviceSe} from 'react-native-trustdevice';

const info = await TrustDevice.getDeviceInfoAsync();
// For a standard-edition integration:
// const info = await TrustDeviceSe.getDeviceInfoAsync();

const captcha = await TrustDevice.showCaptcha();
// captcha.function is onSuccess or onFailed; onReady is emitted as
// a TrustDeviceCaptcha event (TrustDeviceSeCaptcha for the standard module).
const liveness = await TrustDevice.showLiveness({license: 'YOUR_LICENSE'});
// liveness.function is onSuccess or onFailed.
```

### AndroidManifest.xml

Declare the following permissions in the AndroidManifest.xml file under the application module

```xml
<manifest>
   <!-- required -->
   <uses-permission android:name="android.permission.INTERNET"/>
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
   <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
  <!-- Outside the Chinese Mainland -->
  <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

   <!--optional, If not declared, some device information will be abandoned -->
   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
   <uses-permission android:name="android.permission.READ_PHONE_STATE" />
   <!-- required for Android 11 and above to obtain the installed packages -->
   <uses-permission android:name="android.permission.QUERY_ALL_PACKAGES"
        tools:ignore="QueryAllPackagesPermission" />
</manifest>
```

### Permissions

| Name                               | Description                                                                                       |
| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
| **INTERNET**(required)             | Allows the app to access the network connection and send requests to communicate with the server. |
| **ACCESS_NETWORK_STATE**(required) | Collect network connection status information.                                                    |
| **ACCESS_WIFI_STATE**(required)    | Collect the current WiFi access status and WLAN hotspot information.                              |
| **AD_ID**(required)                | Collect the Google advertising ID, required outside the Chinese Mainland.                         |
| ACCESS_COARSE_LOCATION             | Get location information, with an accuracy of approximately 30 to 1500 meters.                    |
| ACCESS_FINE_LOCATION               | Get location information, with positioning accuracy within 10 meters.                             |
| READ_PHONE_STATE                   | Collect information on SIM card                                                                   |
| QUERY_ALL_PACKAGES                 | Collect installed packages                                                                        |

## Initialization

### Cautions

- Ensure that it is initialized after the user agrees to the privacy agreement.

### Definition

```tsx
   async function initWithOptions(options: {[key: string]: any})
```

## Get blackBox

### Cautions

- Call `getBlackBox` after `initWithOptions`.
- Don't cache blackBox returned by getBlackBox in the app. Please rely on this function to get blackBox.

### Definition

```tsx
  // get by synchronous call 
  async function getBlackBox();
  // get by asynchronous call
  async function getBlackBoxAsync();
```

## Behavior collection

Initialize the SDK before starting collection. There must be a real user
interaction such as typing, tapping, or scrolling between `start` and
`collect`; otherwise `collect` may return code `104`.

```tsx
await TrustDevice.start();

const result = await TrustDevice.collect();
// result: {code: number, payload: string, msg: string}

await TrustDevice.stop();
```

`collect` returns and clears the currently buffered behavior data. `stop`
stops collection and clears any uncollected data.

## Best Practices

1. Get TrustDevice Module

```tsx
  const TrustDevice = NativeModules.TrustDevice;
```

2. Initialize and get blackBox

```tsx
  async function initWithOptions() {

    var options = {
      "partner": "[Your partner]",
      "appKey": "[Your appKey]",
      "appName": "[Your appName]",
      "dataCenter": "[Your dataCenter]",
      "debug": false, 
    }

    const isDebugMode = __DEV__;
    // !!! If not set this parameter in DEBUG mode, the app will terminate
    if (isDebugMode) {
      options["debug"] = true;
    }

     TrustDevice.initWithOptions(options);
     const blackBox = await TrustDevice.getBlackBoxAsync()
  }
```

3. Obtain blackBox in actual business scenarios

```tsx
  async function register() {
    const blackBox = await TrustDevice.getBlackBox()
    // ...
  }
```

## Status Check

1. getBlackBox() will return a 26-bit string while initialization successfully: `rGPGX1678775227I9NCwcuVJCb`。
2. getBlackBox() will return a string of around 5000 bits while initialization Failed, please refer to [overview-definition](https://en-doc.trustdecision.com/reference/terminal-sdk-overview-2-0-en)

# Other

## Get SDK Version

```tsx
  async function getSDKVersion();
```

## Keep Configuration

```xml
-keep class com.trustdecision.**{*;}
```

## All Configuration

| Key                | Description                                                                                                                   | 平台      | Sample                               |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------ |
| partner(required)  | Partner code, contact operator to obtain.                                                                                     | All     | options["partner"] = "your partner"  |
| appKey(required)   | Application identification, please refer to[how to get appKey](https://en-doc.trustdecision.com/reference/android-get-appkey) | All     | options["appKey"] = "your appKey"    |
| dataCenter(required)  | Data-center： **cn** for China  **fra** for Europe  **sg** for Singapore  **inda** for Indonesia  **us** for the USA           | All     | options["dataCenter"] = "your dataCenter"  |
| appName            | Application name, contact operator to obtain                                                                                  | All     | options["appName"] = "your appName"  |
| debug              | Allow debugging, default false, must be closed before the application release.                                                | All     | options["debug"] = true              |
| timeLimit          | Network timeout configuration, in seconds, default 15s                                                                        | All     | options["timeLimit"] = 5             |
| location           | whether collecting GPS location information, default allowed                                                                  | All     | options["location"] = true           |
| collectLevel       | You can set M to control the maximum length of blackBox to 2000, default around 5000                                          | All     | options["collectLevel"] = "M"        |
| IDFA               | Whether collecting IDFA information, default allowed                                                                          | iOS     | options["IDFA"] = true               |
| deviceName         | Whether collecting device name, default allowed                                                                               | iOS     | options["deviceName"] = true         |
| runningTasks       | Whether collecting running tasks, default allowed                                                                             | Android | options["runningTasks"] = true       |
| sensor             | Whether collecting sensor information, default allowed                                                                        | Android | options["sensor"] = true             |
| readPhone          | Whether collecting READ _PHONE_ STATE permission-related information, default allowed                                         | Android | options["readPhone"] = true          |
| installPackageList | Whether collecting application list information, default allowed                                                              | Android | options["installPackageList"] = true |
