Expo TrackingTransparency

用于跟踪应用用户和管理跟踪权限的库。

Android

iOS

tvOS

Included in Expo Go

GitHub

npm

更新日志

Recommended version:

~58.0.0

一个用于跟踪应用用户并管理跟踪权限的库。提供对广告标识符的访问，并管理跟踪所需的权限。用于跟踪的数据示例包括电子邮件地址、设备 ID、广告 ID 等。如果设备级设置“允许 App 请求跟踪”处于关闭状态，此权限将被拒绝。请务必将 NSUserTrackingUsageDescription 添加到你的 Info.plist，以说明如何跟踪用户。否则，你的 App 将被 Apple 拒绝。

有关 Apple App Tracking Transparency 框架的更多信息，请参阅其文档。

安装

Terminal

- npx expo install expo-tracking-transparency

- yarn expo install expo-tracking-transparency

- pnpm expo install expo-tracking-transparency

- bun expo install expo-tracking-transparency

If you are installing this in an existing React Native app, make sure to install expo in your project.

在应用配置中配置

如果你的项目使用配置插件（Continuous Native Generation（CNG）），你可以使用内置的配置插件配置 expo-tracking-transparency。该插件允许你配置各种无法在运行时设置、必须通过构建新的应用二进制文件才能生效的属性。如果你的应用不使用 CNG，则需要手动配置此库。

Example app.json with config plugin

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-tracking-transparency",
        {
          "userTrackingPermission": "This identifier will be used to deliver personalized ads to you."
        }
      ]
    ]
  }
}

Configurable properties

Name	Default	Description
`userTrackingPermission`	`"Allow this app to collect app-related data that can be used for tracking you or your device."`	Only for: iOS Sets the iOS `NSUserTrackingUsageDescription` permission message in Info.plist.

若要本地化此 iOS 权限提示，请将 userTrackingPermission 保持为默认值，并在每个语言环境文件的 ios 对象中添加 NSUserTrackingUsageDescription。Expo 会在预构建期间将本地化值写入 InfoPlist.strings。

Are you using this library in an existing React Native app?

如果你未使用 Continuous Native Generation（CNG）（即手动使用原生 android 和 ios 项目），则需要在原生项目中配置以下权限：

对于 Android，将 com.google.android.gms.permission.AD_ID 权限添加到项目的 android/app/src/main/AndroidManifest.xml。
```
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
```

对于 iOS，将 NSUserTrackingUsageDescription 键添加到项目的 ios/[app]/Info.plist：

<key>NSUserTrackingUsageDescription</key>
<string>Your custom usage description string here.</string>

用法

基本跟踪透明度用法

import { useEffect } from 'react';
import { Text, StyleSheet, View } from 'react-native';
import { requestTrackingPermissionsAsync } from 'expo-tracking-transparency';

export default function App() {
  useEffect(() => {
    (async () => {
      const { status } = await requestTrackingPermissionsAsync();
      if (status === 'granted') {
        console.log('Yay! I have user permission to track data');
      }
    })();
  }, []);

  return (
    <View style={styles.container}>
      <Text>Tracking Transparency Module Example</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});

API

import * as ExpoTrackingTransparency from 'expo-tracking-transparency';

Hooks

`useTrackingPermissions(options)`

Android

iOS

tvOS

Parameter	Type
options(optional)	`PermissionHookOptions<object>`

Check or request the user to authorize or deny access to app-related data that can be used for tracking the user or the device. Examples of data used for tracking include email address, device ID, advertising ID, and so on. On iOS, if the user denies this permission, any attempt to collect the IDFA will return a string of 0s.

The system remembers the user’s choice and doesn’t prompt again unless a user uninstalls and then reinstalls the app on the device.

On Android, this method always returns that the permission was granted.

Returns:

[PermissionResponse | null, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]

Example

const [status, requestPermission] = useTrackingPermissions();

Methods

`getAdvertisingId()`

Android

iOS

tvOS

Gets the advertising ID, a UUID string intended only for advertising. Use this string for frequency capping, attribution, conversion events, estimating the number of unique users, advertising fraud detection, and debugging.

As a best practice, don't store the advertising ID. Instead, call this function each time your app needs to use the advertising ID. Users can change whether they allow app tracking and can reset their advertising ID at any time in their system settings. Check your app's authorization using getTrackingPermissionsAsync() to determine the user's intent.

On Android, this function returns the "Android Advertising ID" (AAID). On Android devices that support multiple users, including guest users, it's possible for your app to obtain different advertising IDs on the same device. These different IDs correspond to different users who could be signed in on that device. See Google's documentation for more information: Get a user-resettable advertising ID.

On iOS, this function returns the "Identifier for Advertisers" (IDFA), a string that's unique to each device. Your app must request tracking authorization using requestTrackingPermissionsAsync() before it can get the advertising identifier.

Returns:

string | null

Returns either a UUID string or null. It returns null in the following cases:

On Android, when the system's Limit Ad Tracking setting is enabled (the app user has opted out of ad personalization)
In the iOS simulator, regardless of any settings
On iOS if you haven't received permission using requestTrackingPermissionsAsync()
On iOS, if you've requested permission and the user declines
On iOS, when a profile or configuration restricts access to the advertising identifier, such as when the user has turned off the system-wide "Allow Apps to Request to Track" setting

Example

ExpoTrackingTransparency.getAdvertisingId();
// "E9228286-4C4E-4789-9D95-15827DCB291B"

`getTrackingPermissionsAsync()`

Android

iOS

tvOS

Checks whether or not the user has authorized the app to access app-related data that can be used for tracking the user or the device. See requestTrackingPermissionsAsync for more details.

On Android, this method always returns that the permission was granted.

Returns:

Promise<PermissionResponse>

Example

const { granted } = await getTrackingPermissionsAsync();

if (granted) {
  // Your app is authorized to track the user or their device
}

`isAvailable()`

Android

iOS

tvOS

Returns whether the TrackingTransparency API is available on the current device.

Returns:

boolean

On devices where the Tracking Transparency API is unavailable, the get and request permissions methods will always resolve to granted.

`requestTrackingPermissionsAsync()`

Android

iOS

tvOS

Requests the user to authorize or deny access to app-related data that can be used for tracking the user or the device. Examples of data used for tracking include email address, device ID, advertising ID, and so on. On iOS, if the user denies this permission, any attempt to collect the IDFA will return a string of 0s.

The system remembers the user’s choice and doesn’t prompt again unless a user uninstalls and then reinstalls the app on the device.

On Android, this method always returns that the permission was granted.

Returns:

Promise<PermissionResponse>

Example

const { granted } = await requestTrackingPermissionsAsync();

if (granted) {
  // Your app is authorized to track the user or their device
}

Types

`PermissionExpiration`

Android

iOS

tvOS

Literal type: union

Permission expiration time. Currently, all permissions are granted permanently.

Acceptable values are: 'never' | number

`PermissionHookOptions`

Android

iOS

tvOS

Literal type: union

Acceptable values are: PermissionHookBehavior | Options

`PermissionResponse`

Android

iOS

tvOS

An object obtained by permissions get and request functions.

Property	Type	Description
canAskAgain	`boolean`	Indicates if user can be asked again for specific permission. If not, one should be directed to the Settings app in order to enable/disable the permission.
expires	`PermissionExpiration`	Determines time when the permission expires.
granted	`boolean`	A convenience boolean that indicates if the permission is granted.
status	`PermissionStatus`	Determines the status of the permission.

Enums

`PermissionStatus`

Android

iOS

tvOS

`DENIED`

PermissionStatus.DENIED ＝ "denied"

User has denied the permission.

`GRANTED`

PermissionStatus.GRANTED ＝ "granted"

User has granted the permission.

`UNDETERMINED`

PermissionStatus.UNDETERMINED ＝ "undetermined"

User hasn't granted or denied the permission yet.

权限

Android

此库会通过 AndroidManifest.xml 自动添加以下权限。

Android 权限	描述
`com.google.android.gms.permission.AD_ID`	允许访问用于跟踪和分析的广告 ID。对于面向 Android 13（API 级别 33）或更高版本、且使用 Google Play 服务广告 ID 的应用，此权限为必需。

iOS

此库使用以下用法描述键：

Info.plist key	Description
`NSUserTrackingUsageDescription`	A message that informs the user why an app is requesting permission to use data for tracking the user or the device.