跳转到主要内容
本指南将引导您使用 Android Studio 将 OneSignal 添加到您的 Android 应用中。您将安装我们的 SDK,设置推送通知和应用内消息,并发送测试消息以确认一切正常工作。 如果这是您首次使用 OneSignal,请按顺序完成这些步骤。如果您有经验,可以直接跳转到需要的部分。
使用 AI 编程助手? 如需 AI 驱动的安装,请使用以下提示:
Integrate the OneSignal Android SDK into this codebase.

Follow the instructions at:
https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/android/ai-prompt.md

步骤 0. 在 OneSignal 中配置 FCM(推送送达必需)

您可以在未完成此步骤的情况下安装和初始化 OneSignal Android SDK。但是,在 OneSignal 应用中配置 Firebase Cloud Messaging (FCM) 凭据之前,推送通知将无法送达
如果您的公司已有 OneSignal 账户,请要求以管理员角色被邀请以配置该应用。否则,请注册免费账户开始使用。
这些步骤将您的 OneSignal 应用连接到 Firebase Cloud Messaging (FCM)。每个应用只需执行一次。
  1. 登录 https://onesignal.com 并创建或选择您的应用。
  2. 导航到 Settings > Push & In-App
  3. 选择 Google Android (FCM)Continue 完成设置向导。
  4. 输入您的 Firebase 服务器密钥或服务账户详细信息。
  5. 继续完成设置向导以获取您的 App ID。这将用于初始化 SDK。
有关完整的设置说明,请参阅我们的移动推送设置指南。

设置合约和要求

本节总结了本指南中使用的工具、版本和前提条件。
  • SDK 版本: 5.6.1+(最新版:查看 releases
  • AI 设置说明: https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/android/ai-prompt.md
  • SDK 仓库: https://github.com/OneSignal/OneSignal-Android-SDK
  • Android Studio: Meerkat+(2024.2.1+)
  • Android API: 最低 23+(Android 6.0+),推荐 31+(Android 12+)
  • 设备/模拟器: Android 7.0+ 且已安装 Google Play Services
  • 必需依赖: com.onesignal:OneSignal:[5.6.1, 5.6.99]
  • Application 类: SDK 正确初始化所必需
  • App ID 格式: 36 个字符的 UUID(示例:12345678-1234-1234-1234-123456789012)— 在 OneSignal 控制面板 > Settings > Keys & IDs 中查找
  • 初始化: OneSignal.initWithContext(this, "YOUR_APP_ID")
  • 电池优化: 可能影响后台通知
  • 推荐: 通过 OneSignal.login("user_id") 分配 External ID 以统一跨设备用户

Android 设置步骤

完成以下步骤后,您将:
  • 在您的 Android 应用中安装并初始化 OneSignal SDK
  • 在真实设备上正确提示推送通知权限
  • 成功送达测试推送和应用内消息
如果您跳过了步骤 0(在 OneSignal 中配置 FCM),您仍然可以完成以下 Android Studio 设置。请在测试或发送推送通知之前完成步骤 0。

步骤 1. 添加 OneSignal SDK

  1. 在 Android Studio 中,打开您的 build.gradle.kts (Module: app)build.gradle (Module: app) 文件
  2. 将 OneSignal 添加到您的 dependencies 部分:
implementation("com.onesignal:OneSignal:[5.6.1, 5.6.99]")
  1. 同步 Gradle: 点击出现的横幅中的 Sync Now 或前往 File > Sync Project with Gradle Files
验证 Gradle 同步成功完成且没有依赖冲突。

步骤 2. 创建并配置 Application 类

最佳实践是在 Application 类的 onCreate 方法中初始化 OneSignal,以确保在所有入口点都能正确设置 SDK。 如果您还没有 Application 类,请创建一个:
  1. File > New > Kotlin Class/File(或 Java Class)
  2. 名称:ApplicationClass(或您首选的名称)
将以下 OneSignal 代码添加到 Application 类中。 YOUR_APP_ID 替换为您在 Dashboard > Settings > Keys & IDs 中获取的实际 OneSignal App ID。
// FILE: ApplicationClass.kt
// PURPOSE: Initialize OneSignal when your app launches
// REQUIREMENT: Must be registered in AndroidManifest.xml

package com.your.package.name // Replace with your actual package name

import android.app.Application
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

import com.onesignal.OneSignal
import com.onesignal.debug.LogLevel

class ApplicationClass : Application() {
    override fun onCreate() {
        super.onCreate()

        // Enable verbose logging to debug issues (remove in production)
        OneSignal.Debug.logLevel = LogLevel.VERBOSE

        // Replace with your 36-character App ID from Dashboard > Settings > Keys & IDs
        OneSignal.initWithContext(this, "YOUR_APP_ID")

        // Prompt user for push notification permission
        // In production, consider using an in-app message instead for better opt-in rates
        CoroutineScope(Dispatchers.IO).launch {
            OneSignal.Notifications.requestPermission(false)
        }
    }
}
不建议在 Activity(如 MainActivity)中初始化,因为通过深度链接或通知冷启动应用时可能不会调用它。请始终在 Application 类中初始化 OneSignal 以确保可靠性。
注册 Application 类:
  1. 打开应用的 AndroidManifest.xml
  2. <application> 标签中添加 android:name=".ApplicationClass"(如果您设置了不同的类名,请替换 .ApplicationClass)。
AndroidManifest.xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <application
        android:name=".ApplicationClass"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        ...
      </application>

  </manifest>
验证应用构建并运行无错误。

步骤 3. 配置默认通知图标(推荐)

自定义通知图标以匹配您的应用品牌。此步骤是可选的,但为了专业外观建议完成。

步骤 4. 测试集成

验证订阅创建:
  1. 在带有 Google Play Services 的设备或模拟器上启动应用
  2. 检查 Dashboard > Audience > Subscriptions — 状态显示 “Never Subscribed”
  3. 当权限提示出现时接受
  4. 刷新控制面板 — 状态变为 “Subscribed”
iOS 和 Android 推送权限提示示例。
控制面板显示状态为 'Never Subscribed' 的订阅。
允许推送权限后,刷新控制面板可看到订阅状态更新为 'Subscribed'。
您已成功创建了一个移动订阅。 移动订阅在用户首次在设备上打开您的应用或卸载后重新安装时创建。

创建测试订阅和细分

  1. 点击订阅旁边的 > Add to Test Subscriptions > 为其命名
  2. 前往 Audience > Segments > New Segment
  3. 名称:Test Users,添加 Test Users 筛选器 > Create Segment
添加测试订阅。
使用 Test Users 筛选器创建 'Test Users' 细分。
您已成功创建了一个测试用户细分。现在我们可以测试向该设备和测试用户组发送消息。

通过 API 发送测试推送

  1. 导航到 Settings > Keys & IDs
  2. 在提供的代码中,将下方代码中的 YOUR_APP_API_KEYYOUR_APP_ID 替换为您的实际密钥。此代码使用我们之前创建的 Test Users 细分。
curl -X POST 'https://api.onesignal.com/notifications' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'Authorization: Key YOUR_APP_API_KEY' \
  -d '{
    "app_id": "YOUR_APP_ID",
    "target_channel": "push",
    "name": "Testing basic setup",
    "headings": { "en": "👋" },
    "contents": {"en": "Hello world!"},
    "included_segments": ["Test Users"],
    "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
  }'
推送通知中的图片在折叠通知视图中显示较小。展开通知可查看完整图片。
显示确认送达的投递统计(免费计划不可用)。
验证测试设备收到了包含以下内容的通知:
  • 您的自定义图标(如已配置)
  • 展开时的大图
  • Dashboard > Delivery > Sent Messages 显示 “Confirmed” 状态(免费计划不可用)。
  • 未收到通知?请参阅移动推送未显示
  • 没有自定义图标?请验证图标名称为 onesignal_small_icon_default 且位于正确的 drawable 文件夹中。
  • 遇到问题?请将 API 请求和从应用启动到结束的日志复制粘贴到 .txt 文件中,然后将两者发送至 support@onesignal.com

测试应用内消息

  1. 关闭应用 30 秒以上
  2. Dashboard > Messages > In-App > New In-App > 选择 Welcome 模板
  3. 受众:Test Users 细分
  4. 触发器:On app open
  5. 计划:Every time trigger conditions are satisfied
  6. 点击 Make Message Live
  7. 打开应用
使用应用内消息定向 'Test Users' 细分。
应用内 Welcome 消息的自定义示例。
应用内消息调度选项。
设备上显示的 Welcome 应用内消息。
验证测试设备收到了应用内消息。有关更多详情,请参阅应用内消息设置指南。
未看到消息?
  • 开始新会话
    • 您必须关闭或将应用置于后台至少 30 秒后再重新打开。这确保启动新的会话。
    • 有关更多信息,请参阅应用内消息的显示方式
  • 仍在 Test Users 细分中?
    • 如果您重新安装或切换了设备,请将设备重新添加到测试订阅并确认它属于 Test Users 细分。
  • 遇到问题?
    • 在重现上述步骤时按照获取调试日志的说明操作。这将生成额外的日志信息,您可以将其分享至 support@onesignal.com,我们将帮助调查问题所在。
您已成功设置 OneSignal SDK 并学习了以下重要概念:继续阅读本指南以在您的应用中识别用户并设置其他功能。

常见错误和修复

错误 / 症状原因修复方法
Cannot resolve symbol 'OneSignal'未添加 SDK 依赖或未同步 Gradle将依赖添加到 build.gradle 并同步项目
Application class not foundApplication 类未在清单中注册<application> 标签中添加 android:name=".ApplicationClass"
Google Play Services not available模拟器/设备缺少 Play Services使用带有 Play Store 的设备或带有 Google APIs 的模拟器
收到推送但显示默认 Android 图标自定义图标未配置或名称错误创建名为 onesignal_small_icon_default 的通知图标资源
未收到推送通知FCM 未在 OneSignal 中配置完成步骤 0:在 OneSignal 控制面板中配置 FCM 凭据
应用内消息不显示会话未启动或网络问题关闭应用 30 秒以上,重新打开,检查网络连接
Manifest merger failed清单属性冲突检查是否有重复的应用名称或权限冲突
电池优化阻止通知设备电源管理引导用户为您的应用禁用电池优化
无法诊断问题日志信息不足添加详细日志并检查 logcat 输出中的错误

用户管理

之前,我们演示了如何创建移动订阅。现在我们将扩展到使用 OneSignal SDK 通过所有订阅(包括推送、邮件和短信)来识别用户

分配 External ID(推荐)

使用 External ID 通过后端的用户标识符在设备、邮箱地址和电话号码之间一致地识别用户。这确保您的消息在渠道和第三方系统之间保持统一。有关更多详情和 Java 代码示例,请参阅我们的移动 SDK 参考
Kotlin
// Call when user logs in or is identified, safe to call multiple times
// Typically used in a login completion handler, or on app launch if already authenticated
fun onUserAuthenticated(userId: String) {
    OneSignal.login(userId)
}

// If you want to remove the External ID from the Subscription, setting it to an anonymous user
fun onUserLoggedOut() {
    OneSignal.logout()
}
OneSignal 为订阅(Subscription ID)和用户(OneSignal ID)生成唯一的只读 ID。强烈建议通过我们的 SDK 设置 External ID,以便在所有订阅中识别用户,无论它们是如何创建的。在 SDK 参考指南中了解更多关于 login 方法的信息。

添加标签和自定义事件

标签和自定义事件都是向用户添加数据的方式。标签是 key-value 字符串,通常与用户属性相关联(如 usernamerolestatus),而自定义事件具有 JSON 格式,通常与操作相关联(如 new_purchaseabandoned_cart 及相关属性)。两者都可用于驱动高级消息个性化和 Journeys。有关更多详情和 Java 代码示例,请参阅我们的移动 SDK 参考
Kotlin
// Add a tag when the user's name is set
OneSignal.User.addTag("username", "john_doe")

// Create a custom event when user abandoned a cart
val properties = mapOf(
    "product_id" to "123456",
    "product_name" to "Product Name",
    "product_price" to 100,
    "product_quantity" to 1
)
OneSignal.User.trackEvent("abandoned_cart", properties)
有关如何使用标签和自定义事件的更多详情,请参阅标签自定义事件指南。

添加邮件和/或短信订阅

除了推送通知外,您还可以通过邮件和短信渠道联系用户。如果邮箱地址和/或电话号码已存在于 OneSignal 应用中,SDK 会将其添加到现有用户 — 不会创建重复项。有关更多详情和 Java 代码示例,请参阅我们的移动 SDK 参考
Kotlin
// Add email subscription
// Call when user provides their email (e.g., account creation, settings update) after calling OneSignal.login("user_id")
OneSignal.User.addEmail("user@example.com")

// Add SMS subscription
// Use E.164 format: + country code + number
// Call when user provides their phone number (e.g., account creation, settings update) after calling OneSignal.login("user_id")
OneSignal.User.addSms("+15551234567")
通过 External ID 统一推送、邮件和短信订阅的用户资料。
多渠道通信最佳实践
  • 在添加邮件或短信订阅之前获取明确同意。
  • 向用户说明每个通信渠道的好处。
  • 提供渠道偏好设置,让用户选择他们偏好的渠道。

隐私和用户同意

要控制 OneSignal 何时收集用户数据,请使用 SDK 的同意管理方法。有关更多详情和 Java 代码示例,请参阅我们的移动 SDK 参考
Kotlin
// In ApplicationClass onCreate(), BEFORE OneSignal.initWithContext()
// Use this if your app requires GDPR or other privacy consent before data collection
OneSignal.consentRequired = true

// Later, after user grants consent (e.g., taps "I Agree" on your consent screen)
OneSignal.consentGiven = true
有关更多信息,请参阅我们的隐私和安全文档:

推送权限提示

不要在应用打开时立即调用 requestPermission(),而是采取更具策略性的方法。使用应用内消息在请求权限之前向用户说明推送通知的价值。 有关最佳实践和实现详情,请参阅我们的推送权限提示指南。

监听推送、用户和应用内事件

使用 SDK 监听器来响应用户操作和状态变化。在 OneSignal.initWithContext() 之后将这些添加到您的 Application 类中。

推送通知事件

Kotlin
// Add click listener to handle when users tap notifications
val clickListener = object : INotificationClickListener {
  override fun onClick(event: INotificationClickEvent) {
    Log.d("OneSignal", "Notification clicked: ${event.notification.title}")
  }
}
OneSignal.Notifications.addClickListener(clickListener)

用户状态变化

示例展示了如何使用推送订阅观察者。其他用户状态事件,如用户状态观察者和通知权限观察者,可在移动 SDK 参考中找到。
Kotlin
// Add subscription observer to track push subscription changes
class MyObserver : IPushSubscriptionObserver {
  init {
    OneSignal.User.pushSubscription.addObserver(this)
  }

  override fun onPushSubscriptionChange(state: PushSubscriptionChangedState) {
    if (state.current.optedIn) {
      println("User is now opted-in with push token: ${state.current.token}")
    }
  }
}

应用内消息事件

其他应用内消息方法可在移动 SDK 参考中找到。
Kotlin
// Add click listener for in-app message interactions
val clickListener = object : IInAppMessageClickListener {
  override fun onClick(event: IInAppMessageClickEvent) {
    print(event.result.actionId)
  }
}
OneSignal.InAppMessages.addClickListener(clickListener)

高级设置和功能

Android 特定功能

通用功能

有关完整的 SDK 方法文档,请访问移动 SDK 参考
需要帮助?与我们的支持团队聊天或发送邮件至 support@onesignal.com请包含以下信息:
  • 您遇到的问题详情以及复现步骤(如有)
  • 您的 OneSignal 应用 ID
  • 外部 ID 或订阅 ID(如适用)
  • 您在 OneSignal 控制台中测试的消息 URL(如适用)
  • 任何相关的日志或错误信息
我们很乐意为您提供帮助!