# Android SDK 基础集成指南

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

## 先决条件

要将 Pushwoosh Android SDK 集成到您的应用中，您需要满足以下条件：

<TranslatedFragment id="prerequisites-android" />

## 集成步骤

### 1. 设置 Firebase Cloud Messaging

首先，将您的 Android 项目与 Firebase 连接：

- 在 Android Studio 中打开您的项目
- 导航至 **Tools > Firebase > Cloud Messaging** 并点击“Set up Firebase Cloud Messaging”
- 按照向导的说明进行操作。在最后一步，向导会将必要的依赖项添加到您的 `build.gradle` 文件中

### 2. 添加 Pushwoosh SDK

将 pushwoosh 库依赖项添加到您应用程序的 build.gradle 中：

```groovy title="build.gradle"
implementation 'com.pushwoosh:pushwoosh-firebase:6.+'
```

将“+”替换为[Pushwoosh Android SDK](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/latest) 的当前版本

### 3. 将 Pushwoosh 元数据添加到 AndroidManifest.xml

打开您的 AndroidManifest.xml 文件，并在 `<application>` 标签内添加以下元数据：

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

其中：
- `com.pushwoosh.appid` 是您的 Pushwoosh Application Code
- `com.pushwoosh.apitoken` 是您的 [Pushwoosh Device API Token](/zh/developer/api-reference/api-access-token/#device-api-token)

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

### 4. 初始化代码

通过将此代码添加到您的初始化逻辑中来注册推送通知：

```java
Pushwoosh.getInstance().registerForPushNotifications()
```

### 5. 运行项目

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

## 扩展集成

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

### 推送通知

在 Pushwoosh SDK 中，有两个回调用于处理推送通知：
- `onMessageReceived`：当收到推送通知时调用此方法。
- `onMessageOpened`：当用户与通知交互（打开）时调用此方法

这些回调使开发人员能够在其应用程序中管理推送通知的接收和用户交互：

```xml title="AndroidManifest.xml"
<meta-data
    android:name="com.pushwoosh.notification_service_extension"
    android:value="com.your.package.YourNotificationServiceExtension" />
```

<Tabs syncKey="code-example">
<TabItem label="Kotlin">
```kotlin
import android.util.Log
import com.pushwoosh.notification.NotificationServiceExtension
import com.pushwoosh.notification.PushMessage

class YourNotificationServiceExtension : NotificationServiceExtension() {
    
    override fun onMessageReceived(data: PushMessage): Boolean {
        Log.d("Pushwoosh", "onMessageReceived: ${data.toJson()}")
        return false
    }

    override fun onMessageOpened(message: PushMessage) {
        Log.d("Pushwoosh", "onMessageOpened: ${message.toJson()}")
    }

}
```
</TabItem>
<TabItem label="Java">
```java
import android.util.Log;
import com.pushwoosh.notification.NotificationServiceExtension;
import com.pushwoosh.notification.PushMessage;

public class YourNotificationServiceExtensionJava extends NotificationServiceExtension {

    @Override
    public boolean onMessageReceived(PushMessage data) {
        Log.d("Pushwoosh", "onMessageReceived: " + data.toJson());
        return false;
    }

    @Override
    public void onMessageOpened(PushMessage message) {
        Log.d("Pushwoosh", "onMessageOpened: " + message.toJson());
    }
}
```
</TabItem>
</Tabs>

### 用户配置

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

<Tabs syncKey="code-example">
<TabItem label="Kotlin">
```kotlin
import com.pushwoosh.Pushwoosh
import com.pushwoosh.tags.TagsBundle
import java.util.Date

class Registration {

    public void afterUserLogin(User user) {
        Pushwoosh pushwoosh = Pushwoosh.getInstance()

        // 设置用户 ID
        if (user.getUserId() != null) {
            pushwoosh.setUserId(user.getUserId())
        }

        // 设置用户邮箱
        if (user.getEmail() != null) {
            pushwoosh.setEmail(user.getEmail())
        }

        // 将其他用户信息设置为 Pushwoosh 的标签
        if (user.getUserDetails() != null) {
            val details = user.getUserDetails()
            val tagsBuilder = TagsBundle.Builder()
            
            if (details.getAge() != null) {
                tagsBuilder.putInt("age", details.getAge())
            }
            
            if (details.getUserName() != null) {
                tagsBuilder.putString("name", details.getUserName())
            }
            
            if (details.lastLoginDate() != null) {
                tagsBuilder.putDate("last_login", details.getLastLoginDate())
            }
            
            // 构建并发送标签
            val tags = tagsBuilder.build()
            if (!tags.isEmpty()) {
                pushwoosh.setTags(tags)
            }
        }
    }
}
```
</TabItem>
<TabItem label="Java">
```java
import com.pushwoosh.Pushwoosh;
import com.pushwoosh.tags.TagsBundle;
import java.util.Date;

public class Registration {

    public void afterUserLogin(User user) {
        Pushwoosh pushwoosh = Pushwoosh.getInstance();

        // 设置用户 ID
        if (user.getUserId() != null) {
            pushwoosh.setUserId(user.getUserId());
        }

        // 设置用户邮箱
        if (user.getEmail() != null) {
            pushwoosh.setEmail(user.getEmail());
        }

        // 设置用户短信号码
        if (user.getSmsNumber() != null) {
            pushwoosh.registerSMSNumber(user.getSmsNumber());
        }

        // 设置用户 WhatsApp 号码
        if (user.getWhatsAppNumber() != null) {
            pushwoosh.registerWhatsappNumber(user.getWhatsAppNumber());
        }

        // 将其他用户信息设置为 Pushwoosh 的标签
        if (user.getUserDetails() != null) {
            UserDetails details = user.getUserDetails();
            TagsBundle.Builder tagsBuilder = new TagsBundle.Builder();

            if (details.getAge() != null) {
                tagsBuilder.putInt("age", details.getAge());
            }

            if (details.getUserName() != null) {
                tagsBuilder.putString("name", details.getUserName());
            }

            if (details.getLastLoginDate() != null) {
                tagsBuilder.putDate("last_login", details.getLastLoginDate());
            }

            // 构建并发送标签
            TagsBundle tags = tagsBuilder.build();
            if (!tags.isEmpty()) {
                pushwoosh.setTags(tags);
            }
        }
    }
}
```
</TabItem>
</Tabs>

### 标签

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

<Tabs syncKey="code-example">
<TabItem label="Kotlin">
```kotlin
import com.pushwoosh.Pushwoosh
import com.pushwoosh.tags.TagsBundle
import java.util.List

class UpdateUser {
    public void afterUserUpdateProfile(User user) {
        val pushwoosh = Pushwoosh.getInstance()
        val tagsBuilder = TagsBundle.Builder()

        // 设置收藏类别列表
        if (user.favoriteCategories != null && user.favoriteCategories.isNotEmpty()) {
            tagsBuilder.putList("favorite_categories", user.getFavoriteCategories())
        }

        // 设置支付信息
        tagsBuilder.putBoolean("is_subscribed", user.isSubscribed())
        tagsBuilder.putString("payment_status", user.getPaymentStatus())
        tagsBuilder.putString("billing_address", user.getBillingAddress())

        // 构建并发送标签
        pushwoosh.setTags(tagsBuilder.build())
    }
}
```
</TabItem>
<TabItem label="Java">
```java
import com.pushwoosh.Pushwoosh;
import com.pushwoosh.tags.TagsBundle;
import java.util.List;

public class UpdateUser {
    public void afterUserUpdateProfile(User user) {
        Pushwoosh pushwoosh = Pushwoosh.getInstance();
        TagsBundle.Builder tagsBuilder = new TagsBundle.Builder();

        // 设置收藏类别列表
        if (user.getFavoriteCategories() != null && !user.getFavoriteCategories().isEmpty()) {
            tagsBuilder.putList("favorite_categories", user.getFavoriteCategories());
        }

        // 设置支付信息
        tagsBuilder.putBoolean("is_subscribed", user.isSubscribed());
        tagsBuilder.putString("payment_status", user.getPaymentStatus());
        tagsBuilder.putString("billing_address", user.getBillingAddress());

        // 构建并发送标签
        pushwoosh.setTags(tagsBuilder.build());
    }
}
```
</TabItem>
</Tabs>

### 事件

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

<Tabs syncKey="code-example">
<TabItem label="Kotlin">
```kotlin
import com.pushwoosh.Pushwoosh
import com.pushwoosh.inapp.InAppManager
import com.pushwoosh.tags.TagsBundle
import java.util.Date

class Registration {

    public void afterUserLogin(User user) {
        if (user.getUserName() != null && user.getLastLoginDate() != null) {
            val attributes = TagsBundle.Builder()
                .putString("name", user.getUserName())
                .putDate("last_login", user.getLastLoginDate())
                .build()
            
            InAppManager.getInstance().postEvent("login", attributes)
        }
    }

    public void afterUserPurchase(User user, Product product) {
        Pushwoosh pushwoosh = Pushwoosh.getInstance()

        // 跟踪购买事件
        val purchaseAttributes = TagsBundle.Builder()
            .putString("product_id", product.getId())
            .putString("product_name", product.getName())
            .putDouble("price", product.getPrice())
            .putInt("quantity", product.getQuantity())
            .build()
        
        InAppManager.getInstance().postEvent("purchase", purchaseAttributes)

        // 设置用户标签
        val tagsBuilder = TagsBundle.Builder()
        tagsBuilder.putDate("last_purchase_date", Date())
        val lifetimeSpend = getCurrentLifetimeSpend() + product.getPrice()
        tagsBuilder.putDouble("lifetime_spend", getCurrentLifetimeSpend())
        pushwoosh.setTags(tagsBuilder.build())
    }
}
```
</TabItem>
<TabItem label="Java">
```java
import com.pushwoosh.Pushwoosh;
import com.pushwoosh.tags.TagsBundle;
import java.util.Date;

public class Registration {

    public void afterUserLogin(User user) {
        if (user.getUserName() != null && user.getLastLoginDate() != null) {
            TagsBundle attributes = new TagsBundle.Builder()
                .putString("name", user.getUserName())
                .putDate("last_login", user.getLastLoginDate())
                .build();

            Pushwoosh.getInstance().postEvent("login", attributes);
        }
    }

    public void afterUserPurchase(User user, Product product) {
        Pushwoosh pushwoosh = Pushwoosh.getInstance();

        // 跟踪购买事件
        TagsBundle purchaseAttributes = new TagsBundle.Builder()
            .putString("product_id", product.getId())
            .putString("product_name", product.getName())
            .putDouble("price", product.getPrice())
            .putInt("quantity", product.getQuantity())
            .build();

        Pushwoosh.getInstance().postEvent("purchase", purchaseAttributes);

        // 设置用户标签
        TagsBundle.Builder tagsBuilder = new TagsBundle.Builder();
        tagsBuilder.putDate("last_purchase_date", new Date());
        double lifetimeSpend = getCurrentLifetimeSpend() + product.getPrice();
        tagsBuilder.putDouble("lifetime_spend", getCurrentLifetimeSpend());
        pushwoosh.setTags(tagsBuilder.build());
    }
}
```
</TabItem>
</Tabs>

### 富媒体

富媒体是指在通知和应用内消息中使用的交互式多媒体内容，如图像、视频或 HTML，以增强用户参与度


要启用 **Modal Rich Media** 功能，您需要在应用程序的 `AndroidManifest.xml` 文件中添加以下元数据条目进行配置：

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

<Tabs syncKey="code-example">
<TabItem label="Kotlin">
```kotlin
import android.util.Log
import com.pushwoosh.richmedia.RichMedia
import com.pushwoosh.richmedia.RichMediaManager
import com.pushwoosh.richmedia.RichMediaPresentingDelegate
import com.pushwoosh.inapp.view.config.ModalRichmediaConfig
import com.pushwoosh.inapp.view.config.enums.*

class MainActivity : AppCompatActivity(), RichMediaPresentingDelegate {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        RichMediaManager.setDelegate(this)

        // 配置模态富媒体
        val config = ModalRichmediaConfig()
            .setViewPosition(ModalRichMediaViewPosition.BOTTOM)
            .setPresentAnimationType(ModalRichMediaPresentAnimationType.SLIDE_UP)
            .setDismissAnimationType(ModalRichMediaDismissAnimationType.SLIDE_DOWN)
            
        // 应用配置
        RichMediaManager.setDefaultRichMediaConfig(config)
    }
    
    override fun shouldPresent(richMedia: RichMedia): Boolean {
        Log.d("Pushwoosh", "Rich media will be presented with: ${richMedia.content}")
        return true
    }

    override fun onPresent(richMedia: RichMedia) {
        Log.d("Pushwoosh", "Rich media has been presented: ${richMedia.content}")
    }

    override fun onClose(richMedia: RichMedia) {
        Log.d("Pushwoosh", "Rich media has been closed: ${richMedia.content}")
    }

    override fun onError(richMedia: RichMedia, pushwooshException: PushwooshException) {
        Log.e("Pushwoosh", "Failed to present rich media: ${richMedia.content}. Error: ${pushwooshException.message}")
    }
}
```
</TabItem>
<TabItem label="Java">
```java
import android.util.Log;
import com.pushwoosh.richmedia.RichMedia;
import com.pushwoosh.richmedia.RichMediaManager;
import com.pushwoosh.richmedia.RichMediaPresentingDelegate;
import com.pushwoosh.inapp.view.config.ModalRichmediaConfig;
import com.pushwoosh.inapp.view.config.enums.*;

public class MainActivity extends AppCompatActivity implements RichMediaPresentingDelegate {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        RichMediaManager.setDelegate(this);

        // 配置模态富媒体
        ModalRichmediaConfig config = new ModalRichmediaConfig()
            .setViewPosition(ModalRichMediaViewPosition.BOTTOM)
            .setPresentAnimationType(ModalRichMediaPresentAnimationType.SLIDE_UP)
            .setDismissAnimationType(ModalRichMediaDismissAnimationType.SLIDE_DOWN);

        // 应用配置
        RichMediaManager.setDefaultRichMediaConfig(config);
    }

    @Override
    public boolean shouldPresent(RichMedia richMedia) {
        Log.d("Pushwoosh", "Rich media will be presented with: " + richMedia.getContent());
        return true;
    }

    @Override
    public void onPresent(RichMedia richMedia) {
        Log.d("Pushwoosh", "Rich media has been presented: " + richMedia.getContent());
    }

    @Override
    public void onClose(RichMedia richMedia) {
        Log.d("Pushwoosh", "Rich media has been closed: " + richMedia.getContent());
    }

    @Override
    public void onError(RichMedia richMedia, PushwooshException pushwooshException) {
        Log.e("Pushwoosh", "Failed to present rich media: " + richMedia.getContent() + ". Error: " + pushwooshException.getMessage());
    }
}
```
</TabItem>
</Tabs>

## 故障排除

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