# React Native SDK 基本集成指南

本节包含有关如何将 Pushwoosh React Native SDK 集成到您的应用程序中的信息。

## 先决条件

要将 Pushwoosh React Native SDK 集成到您的应用中，您需要以下内容：

<Aside type="note" title="要求">
 - 一个 [Pushwoosh 账户](https://sso.pushwoosh.com/login)。
 - 在您的账户中设置一个 [Pushwoosh 项目](/zh/product/first-steps/start-with-your-project/create-your-project)。
 - **对于 iOS 集成：**
    - 一个配置为发送推送通知的 iOS 平台。我们建议使用[基于令牌的身份验证配置](/zh/developer/first-steps/connect-messaging-services/ios-configuration/ios-token-based-configuration/)作为最简单的方法。
    - 将网关设置为 `Sandbox` 以向模拟器发送推送。
 - **对于 Android 集成：**
    - 一个[已配置的 Android 平台](/zh/developer/first-steps/connect-messaging-services/android-configuration/android-firebase-configuration)
    - 来自您的 Firebase 项目的 `google-services.json` 文件和 `package name`。
    - 一个连接到您的 Android 应用程序的 Firebase 项目。如果需要，请遵循 [Firebase 设置指南](https://firebase.google.com/docs/android/setup#manually_add_firebase)。
 - 您的 `Pushwoosh Application Code` 和来自您应用程序的 Pushwoosh 控制面板的 [Pushwoosh Device API Token](/zh/developer/api-reference/api-access-token/#device-api-token)。
</Aside>

## 集成步骤

### 1. 添加 Pushwoosh React Native SDK 依赖

将 Pushwoosh React Native SDK 依赖项添加到您的项目中：

```bash
npm install pushwoosh-react-native-plugin --save
```

### 2. React Native SDK 初始化

在您的 `index.js` 文件的根组件中：
- 导入 `pushwoosh-react-native-plugin`。
- 初始化 Pushwoosh SDK。
- 在您的初始化逻辑中调用 `register()` 以注册推送通知。

```javascript title="index.js"
import Pushwoosh from 'pushwoosh-react-native-plugin';

AppRegistry.registerComponent(appName, () => App);

Pushwoosh.init({
    "pw_appid" : "__YOUR_APP_ID__"
});

Pushwoosh.register();
```

其中：
- `__YOUR_APP_ID__` 是来自 Pushwoosh 控制面板的应用程序代码。


### 3. iOS 原生设置

#### 3.1 功能

要在您的项目中启用推送通知，您需要添加某些功能。

在“Signing & Capabilities”部分，添加以下功能：
- `Push Notifications`
- `Background Modes`。添加此功能后，选中 `Remote notifications` 复选框。

如果您打算使用 Time Sensitive Notifications (iOS 15+)，还需添加 `Time Sensitive Notifications` 功能。

#### 3.2 Info.plist

在您的 `Runner/Info.plist` 中，将 `__PUSHWOOSH_DEVICE_API_TOKEN__` 键设置为 [Pushwoosh Device API Token](/zh/developer/api-reference/api-access-token/#device-api-token)：
```swift title="info.plist"
<key>Pushwoosh_API_TOKEN</key>
<string>__PUSHWOOSH_DEVICE_API_TOKEN__</string>
```

#### 3.3 消息送达跟踪

您必须向您的项目添加一个 Notification Service Extension 目标。这对于准确的送达跟踪和 iOS 上的富媒体等功能至关重要。

请遵循[原生指南的步骤](/zh/developer/pushwoosh-sdk/ios-sdk/setting-up-pushwoosh-ios-sdk/basic-integration-guide/#4-message-delivery-tracking)来添加扩展目标及其中的必要 Pushwoosh 代码。

#### 3.4 为 iOS React Native 项目安装依赖项

要为 iOS React Native 项目安装依赖项，请在终端中导航到 ```ios``` 文件夹并运行：

```bash
pod install --repo-update
```

### 4. Android 原生设置

#### 4.1 安装依赖项

确保所需的依赖项和插件已添加到您的 Gradle 脚本中：

将 Google Services Gradle 插件添加到您的项目级 `build.gradle` 依赖项中：

```groovy title="android/build.gradle"
buildscript {
  dependencies {
    classpath 'com.google.gms:google-services:4.3.15'
  }
}
```

在您的应用级 `build.gradle` 文件中应用该插件：

```groovy title="app/build.gradle"
apply plugin: 'com.google.gms.google-services'
```

#### 4.2 添加 Firebase 配置文件

将 `google-services.json` 文件放入您项目目录的 `android/app` 文件夹中。

#### 4.3 添加 Pushwoosh 元数据

在您的 `main/AndroidManifest.xml` 中，在 `<application>` 标签内添加 [Pushwoosh Device API Token](/zh/developer/api-reference/api-access-token/#device-api-token)：

```xml title="AndroidManifest.xml"
<meta-data android:name="com.pushwoosh.apitoken" android:value="__YOUR_DEVICE_API_TOKEN__" />
```

> **重要提示：** 请确保在您的 Pushwoosh 控制面板中为令牌授予对正确应用的访问权限。[了解更多](/zh/developer/api-reference/api-access-token/#edit-token)

### 5. 运行项目

1. 构建并运行项目。
2. 转到 Pushwoosh 控制面板并[发送推送通知](/zh/product/messaging-channels/push-notifications/send-push-notifications/one-time-push)。
3. 您应该会在应用中看到该通知。

## 扩展集成

至此，您已经集成了 SDK，可以发送和接收推送通知。现在，让我们来探索核心功能。

### 推送通知事件监听器

在 Pushwoosh SDK 中，有两个事件监听器，专为处理推送通知而设计：

- `pushReceived` 事件在收到推送通知时触发
- `pushOpened` 事件在用户打开通知时触发

您应该在应用程序启动时，在 SDK 初始化之后立即设置这些事件监听器：

```javascript
import {DeviceEventEmitter} from 'react-native'
import Pushwoosh from 'pushwoosh-react-native-plugin';

class PushwooshNotificationHandler {
  setupPushListeners() {

    DeviceEventEmitter.addListener('pushReceived', (e) => {
      console.warn("Push received: " + JSON.stringify(e));
    });

    DeviceEventEmitter.addListener('pushOpened', (e) => {
      console.warn("Push accepted: " + JSON.stringify(e));
    });

  }
}
```

### 用户配置

通过关注个人用户的行为和偏好，您可以提供个性化内容，从而提高用户满意度和忠诚度。

```javascript
import Pushwoosh from 'pushwoosh-react-native-plugin';

class Registration {
  afterUserLogin(user: User) {

    // 设置用户 ID
    Pushwoosh.setUserId(user.getId());

    // 设置用户邮箱
    Pushwoosh.setEmails(user.getEmailList());

    // 设置用户短信号码
    Pushwoosh.registerSMSNumber(user.getPhoneNumber());

    // 设置用户 WhatsApp 号码
    Pushwoosh.registerWhatsappNumber(user.getWhatsAppNumber());

    // 将其他用户信息设置为 Pushwoosh 的标签
    Pushwoosh.setTags({
      "age": user.getAge(),
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }
}
```

### 标签 (Tags)

标签是分配给用户或设备的键值对，允许根据偏好或行为等属性进行分段，从而实现有针对性的消息传递。

```javascript
import Pushwoosh from 'pushwoosh-react-native-plugin';

class UpdateUser {
  afterUserUpdateProfile(user: User) {

    // 设置喜爱的类别列表
    Pushwoosh.setTags({
      "favorite_categories": user.getFavoriteCategoriesList()
    });

    // 设置支付信息
    Pushwoosh.setTags({
      "is_subscribed": user.isSubscribed(),
      "payment_status": user.getPaymentStatus(),
      "billing_address": user.getBillingAddress()
    });
  }
}
```

### 事件 (Events)

事件是应用内特定的用户操作或发生的事情，可以被跟踪以分析行为并触发相应的消息或操作。

```javascript
import Pushwoosh from 'pushwoosh-react-native-plugin';

class Registration {

  // 跟踪登录事件
  afterUserLogin(user: User) {
    Pushwoosh.postEvent("login", {
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }

  // 跟踪购买事件
  afterUserPurchase(product: Product) {
    Pushwoosh.postEvent("purchase", {
      "product_id": product.getId(),
      "product_name": product.getName(),
      "price": product.getPrice(),
      "quantity": product.getQuantity()
    });
  }
}
```

## 故障排除

如果您在集成过程中遇到任何问题，请参阅[支持和社区](/zh/developer/pushwoosh-sdk/support-and-community)部分。