使用 C++ 设置 Firebase Cloud Messaging 客户端应用

如需使用 C++ 编写您的跨平台 Firebase Cloud Messaging 客户端应用,请使用 Firebase Cloud Messaging API。C++ SDK 适用于 Android 和 Apple 平台,但这两个平台都还需要一些额外设置。

设置 Firebase 和 FCM SDK

Android

  1. 如果您尚未将 Firebase 添加至您的 C++ 项目,请先添加。

    • 在所链接的设置说明中,查看使用 Firebase C++ SDK 的设备和应用要求,包括使用 CMake 构建应用的建议。

    • 请务必在项目级层 build.gradle 文件中的 buildscriptallprojects 部分添加 Google 的 Maven 代码库。

  2. 创建一个在 JNI 环境和 Activity 中传递内容的 Firebase 应用对象:

    app = ::firebase::App::Create(::firebase::AppOptions(), jni_env, activity);

  3. 定义一个实现 firebase::messaging::Listener 接口的类。

  4. 初始化 FCM,并在应用和一个已构建好的监听器中传递内容:

    ::firebase::messaging::Initialize(app, listener);

  5. 依靠 Google Play 服务 SDK 运行的应用在访问各项功能之前,应检查设备是否拥有兼容的 Google Play 服务 APK。 如需了解详情,请参阅检查 Google Play 服务 APK

iOS+

  1. 您需要一个有效的 APNs 证书。如果您还没有,请务必在 Apple Developer 会员中心创建一个。
  2. 如果您尚未将 Firebase 添加到您的 C++ 项目,请先添加。然后,为 FCM 设置项目:
    1. 在项目的 Podfile 中,添加 FCM 依赖项:
      pod 'FirebaseMessaging'
    2. firebase.frameworkfirebase_messaging.framework 框架从 Firebase C++ SDK 拖动到您的 Xcode 项目中。
  3. 配置 Xcode 项目以启用推送通知:

    1. Navigator 区域 中选择该项目。
    2. Editor 区域中选择项目目标。
    3. Editor 区域中选择 General 标签页。

      1. 向下滚动到 Linked Frameworks and Libraries,然后点击 + 按钮添加框架。
      2. 在显示的窗口中,滚动到 UserNotifications.framework 并点击该条目,然后点击 Add

        此框架仅显示在此库要求使用的 Xcode v8 及更高版本中。

    4. Editor 区域中选择 Capabilities 标签页。

      1. Push Notifications 切换为 On
      2. 向下滚动到 Background Modes,然后将其切换为 On
      3. 选择 Background Modes 下的 Remote notifications
  4. 创建一个 Firebase 应用对象:

    app = ::firebase::App::Create(::firebase::AppOptions());

  5. 定义一个实现 firebase::messaging::Listener 接口的类。

  6. 初始化 Firebase Cloud Messaging,并在应用和一个已构建好的监听器中传递内容:

    ::firebase::messaging::Initialize(app, listener);

获取设备注册令牌

初始化 Firebase Cloud Messaging 库时,将为客户端应用实例请求一个注册令牌。应用将通过 OnTokenReceived 回调函数接收令牌,该回调函数应在实现 firebase::messaging::Listener 的类中进行定义。

如果您希望定位该特定设备,就需要获取此令牌。

关于 Android 上的消息传递的注意事项

当应用没有运行而用户点按通知时,默认情况下消息不会通过 FCM 的内置回调进行传递。在这种情况下,消息载荷是通过用于启动应用的 Intent 接收的。如需使 FCM 将这些传入的消息转发到 C++ 库回调,您需要替换 Activity 中的 onNewIntent 方法,并将 Intent 传递给 MessageForwardingService

import com.google.firebase.messaging.MessageForwardingService;

class MyActivity extends Activity {
  private static final String TAG = "MyActvity";

  @Override
  protected void onNewIntent(Intent intent) {
    Log.d(TAG, "A message was sent to this app while it was in the background.");
    Intent message = new Intent(this, MessageForwardingService.class);
    message.setAction(MessageForwardingService.ACTION_REMOTE_INTENT);
    message.putExtras(intent);
    message.setData(intent.getData());
    // For older versions of Firebase C++ SDK (< 7.1.0), use `startService`.
    // startService(message);
    MessageForwardingService.enqueueWork(this, message);
  }
}

当应用在后台时,用户设备接收到的消息会将其通知字段的内容用于填充系统任务栏通知,但该通知内容并不会传输给 FCM。也就是说,Message::notification 将为空。

总结:

应用状态 通知 数据 两者
前台 OnMessageReceived OnMessageReceived OnMessageReceived
后台 系统任务栏 OnMessageReceived 通知:系统任务栏
数据:intent 的 extras 属性。

Android 上的自定义消息处理

默认情况下,发送到应用的通知均传递到 ::firebase::messaging::Listener::OnMessageReceived,但在某些情况下,您可能需要替换默认行为。如需在 Android 上执行此操作,您需要编写用于扩展 com.google.firebase.messaging.cpp.ListenerService 的自定义类,并更新项目的 AndroidManifest.xml

替换 ListenerService 方法。

ListenerService 是用于拦截发送到应用的消息并将它们传递到 C++ 库的 Java 类。当应用处于前台时(或者当应用在后台并收到仅含数据的载荷时),消息将通过此类提供的其中一个回调传递。如需向消息处理添加自定义行为,您需要扩展 FCM 的默认 ListenerService

import com.google.firebase.messaging.cpp.ListenerService;

class MyListenerService extends ListenerService {

通过重写 ListenerService.onMessageReceived 方法,您可以根据收到的 RemoteMessage 对象执行操作并获取消息数据:

@Override
public void onMessageReceived(RemoteMessage message) {
  Log.d(TAG, "A message has been received.");
  // Do additional logic...
  super.onMessageReceived(message);
}

ListenerService 还有其他一些不太常用的方法。这些方法也可以重写,如需了解详情,请参阅 FirebaseMessagingService 参考。

@Override
public void onDeletedMessages() {
  Log.d(TAG, "Messages have been deleted on the server.");
  // Do additional logic...
  super.onDeletedMessages();
}

@Override
public void onMessageSent(String messageId) {
  Log.d(TAG, "An outgoing message has been sent.");
  // Do additional logic...
  super.onMessageSent(messageId);
}

@Override
public void onSendError(String messageId, Exception exception) {
  Log.d(TAG, "An outgoing message encountered an error.");
  // Do additional logic...
  super.onSendError(messageId, exception);
}

更新 AndroidManifest.xml

编写的自定义类必须包含在 AndroidManifest.xml 中才能生效。通过在 <manifest> 标记中声明适当的特性,确保清单文件包含合并工具,如下所示:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.google.firebase.messaging.cpp.samples"
    xmlns:tools="http://schemas.android.com/tools">

firebase_messaging_cpp.aar 归档中,有一个声明 FCM 默认 ListenerServiceAndroidManifest.xml 文件。此清单文件通常与项目特有的清单文件合并,这样 ListenerService 才能够正常运行。此 ListenerService 需要替换为自定义侦听器服务。为此,您可以在项目的 AndroidManifest.xml 文件中添加以下几行代码,以移除默认的 ListenerService 并添加自定义服务:

<service android:name="com.google.firebase.messaging.cpp.ListenerService"
         tools:node="remove" />
<service android:name="com.google.firebase.messaging.cpp.samples.MyListenerService"
         android:exported="false">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT"/>
  </intent-filter>
</service>

新版本的 Firebase C++ SDK(7.1.0 及更高版本)使用 JobIntentService,这需要在 AndroidManifest.xml 文件中进行额外修改。

<service android:name="com.google.firebase.messaging.MessageForwardingService"
     android:permission="android.permission.BIND_JOB_SERVICE"
     android:exported="false" >
</service>

防止自动初始化

FCM 会生成一个用于设备定位的注册令牌。生成令牌时,库会将标识符和配置数据上传到 Firebase。如果您希望在使用令牌之前能够明确地自行选择,则可以通过在配置时停用 FCM(如果是 Android,则还要停用 Analytics)来防止生成该令牌。为此,请向 Apple 平台上的 Info.plist(而不是 GoogleService-Info.plist)或 Android 上的 AndroidManifest.xml 中添加一个元数据值:

Android

<?xml version="1.0" encoding="utf-8"?>
<application>
  <meta-data android:name="firebase_messaging_auto_init_enabled"
             android:value="false" />
  <meta-data android:name="firebase_analytics_collection_enabled"
             android:value="false" />
</application>

Swift

FirebaseMessagingAutoInitEnabled = NO

如需重新启用 FCM,您可以执行运行时调用:

::firebase::messaging::SetTokenRegistrationOnInitEnabled(true);

此值一经设置,就会在应用重启后持久保存。

FCM 允许将包含深层链接的消息发送到您的应用中。如需接收包含深层链接的消息,您必须在为应用处理深层链接的 Activity 中添加一个新的 intent 过滤器,该 intent 过滤器应能捕获您的网域的深层链接。如果您的消息不包含深层链接,则不需要此配置。在 AndroidManifest.xml 中:

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="http"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="https"/>
</intent-filter>

您也可以指定通配符以使 intent 过滤器更加灵活。例如:

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="*.example.com" android:scheme="http"/>
  <data android:host="*.example.com" android:scheme="https"/>
</intent-filter>

当用户点按的通知包含指向您指定的架构和主机的链接时,您的应用将会启动含此 intent 过滤器的 Activity 来处理该链接。

后续步骤

设置客户端应用后,即可使用 Firebase 发送下行消息和主题消息。如需了解更多信息,请参阅“快速入门”示例应用中关于此功能的演示,您可以下载、运行和查看“快速入门”示例应用。

如需向您的应用添加其他更高级的行为,请参阅从应用服务器发送消息的指南:

请注意,您需要完成服务器实现才能利用这些功能。