איך מתחילים להשתמש ב-Firebase Cloud Messaging באפליקציות C++‎

בחירת פלטפורמה:

‫iOS+‎ Android Web Flutter Unity C++‎

במדריך הזה מוסבר איך להתחיל להשתמש ב-Firebase Cloud Messaging באפליקציות לקוח ב-C++‎ כדי לשלוח הודעות בצורה מהימנה.

כדי לכתוב אפליקציית לקוח Firebase Cloud Messaging חוצת פלטפורמות באמצעות C++, משתמשים ב-API‏ Firebase Cloud Messaging. ‫C++ SDK פועל בפלטפורמות Android ו-Apple, אבל צריך לבצע הגדרה נוספת לכל פלטפורמה. כדי לקבל מידע נוסף על אופן הפעולה של C++ SDK ל-iOS ול-Android עם FCM, אפשר לעיין במאמר הסבר על Firebase ל-C++‎.

הגדרת Firebase ו-FCM SDK

Android

1. אם עדיין לא עשיתם זאת, מוסיפים את Firebase לפרויקט C++‎.

   • בהוראות ההגדרה המקושרות, כדאי לעיין בדרישות המכשיר והאפליקציה לשימוש ב-SDK‏ Firebase C++, כולל ההמלצה להשתמש ב-CMake כדי ליצור את האפליקציה.

   • בקובץ build.gradle ברמת הפרויקט, צריך לוודא שמאגר ה-Maven של Google כלול בקטעים buildscript ו-allprojects.

   חשוב: הקפידו להוסיף את ספריית firebase_messaging לקובץ CMakeLists.txt.

2. יוצרים אובייקט Firebase App, ומעבירים את סביבת ה-JNI ואת הפעילות:

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

3. מגדירים מחלקה שמטמיעה את הממשק firebase::messaging::Listener.

4. מאתחלים את FCM ומעבירים את האפליקציה ואת Listener שנבנה:

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

5. אפליקציות שמסתמכות על Google Play Services SDK צריכות לבדוק אם במכשיר יש חבילת APK תואמת של Google Play Services לפני שהן ניגשות לתכונות. מידע נוסף זמין במאמר בנושא בדיקת קובץ ה-APK של Google Play Services.

‫iOS+

1. אם עדיין לא עשיתם זאת, מוסיפים את Firebase לפרויקט C++‎. לאחר מכן, כדי להגדיר את הפרויקט ל-FCM:
   1. בקובץ Podfile של הפרויקט, מוסיפים את התלות ב-FCM:

      pod 'FirebaseMessaging'

   2. גוררים את מסגרות firebase.framework ו-firebase_messaging.framework לפרויקט Xcode מתוך Firebase C++ SDK.

2. מעלים את מפתח האימות של APNs ל-Firebase. אם עדיין אין לכם מפתח אימות של APNs, אתם צריכים ליצור אותו ב-Apple Developer Member Center.

   1. במסוף Firebase, עוברים אל הגדרות > כללי. ואז לוחצים על הכרטיסייה העברת הודעות בענן.
   2. בקטע APNs authentication key (מפתח אימות של APNs) שמתחת לקטע iOS app configuration (הגדרת אפליקציית iOS), לוחצים על Upload (העלאה) כדי להעלות את מפתח האימות של הסביבה לפיתוח, או את מפתח האימות של סביבת הייצור, או את שניהם. צריך להוסיף לפחות תמונה אחת.
   3. מחפשים את המיקום שבו שמרתם את המפתח, בוחרים אותו ולוחצים על פתיחה. מוסיפים את מזהה המפתח (שזמין ב-Apple Developer Member Center) ולוחצים על העלאה.

3. מגדירים את פרויקט Xcode כדי להפעיל התראות:

   1. בוחרים את הפרויקט מאזור הניווט.
   2. בוחרים את יעד הפרויקט מאזור העריכה.

   3. בוחרים בכרטיסייה כללי באזור העריכה.

      1. גוללים אל Linked Frameworks and Libraries (מסגרות וספריות מקושרות) ולוחצים על הלחצן + כדי להוסיף מסגרות.

      2. בחלון שמופיע, גוללים אל UserNotifications.framework, לוחצים על הרשומה ואז על Add.

         המסגרת הזו מופיעה רק ב-Xcode גרסה 8 ואילך, והיא נדרשת על ידי הספרייה הזו.

   4. בוחרים בכרטיסייה יכולות מאזור העריכה.

      1. מעבירים את המתג של התראות למצב מופעל.
      2. גוללים אל מצבי רקע ומעבירים אותו למצב מופעל.
      3. בקטע Background Modes (מצבי רקע), בוחרים באפשרות Remote notifications (התראות מרחוק).

4. יוצרים אובייקט Firebase App:

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

5. מגדירים מחלקה שמטמיעה את הממשק firebase::messaging::Listener.

6. מפעילים את העברת ההודעות בענן ב-Firebase, מעבירים את האפליקציה ואת Listener שהוגדר:

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

גישה למזהה ההתקנה ב-Firebase

הערה: Firebase Cloud Messaging עובר משימוש בטוקנים של רישום ב-FCM לשימוש במזהי התקנה של Firebase (FID) לטירגוט של מופעים ספציפיים של אפליקציות.

הפעלת הרשמה באמצעות מזהה התקנה של Firebase

כדי להפעיל את רישום מופע האפליקציה ב-FCM באמצעות מזהה ההתקנה (FID) של Firebase, צריך קודם להפעיל את מזהי ההתקנה בהגדרות של האפליקציה בפלטפורמות Android ו-Apple:

Android

מוסיפים את רכיב <meta-data> הבא בתוך רכיב <application> של AndroidManifest.xml:

<meta-data android:name="firebase_messaging_installation_id_enabled"
           android:value="true" />

Swift

מוסיפים את המפתח FirebaseMessagingInstallationIdEnabled אל Info.plist ומגדירים אותו לערך YES:

FirebaseMessagingInstallationIdEnabled = YES

הטמעה של onRegistrationReceived Listener

כשמפעילים את הספרייה Firebase Cloud Messaging, היא רושמת את מופע אפליקציית הלקוח לקבלת הודעות באמצעות מזהה התקנה של Firebase‏ (FID). האפליקציה תקבל את ה-FID באמצעות הקריאה החוזרת OnRegistrationReceived, שצריכה להיות מוגדרת בהטמעה שלכם:firebase::messaging::Listener

class MyListener : public firebase::messaging::Listener {
 public:
  void OnRegistrationReceived(const char* installation_id) override {
    LogMessage("Received Firebase Installation ID: %s", installation_id);
    // TODO: Send the Firebase Installation ID (FID) to your app server to
    // target this device for messages.
  }
};

אם רוצים לטרגט את המופע הספציפי של האפליקציה, צריך לשלוח את ה-FID לשרת האפליקציה ולאחסן אותו בשיטה המועדפת.

רישום ידני כשההפעלה האוטומטית מושבתת

אפשר גם להפעיל את הרישום באופן ידני באמצעות FCM בזמן הריצה באמצעות Register():

// Manually register with FCM
firebase::Future<void> register_future = firebase::messaging::Register();
register_future.OnCompletion([](const firebase::Future<void>& future) {
  if (future.status() == firebase::kFutureStatusComplete &&
      future.error() == 0) {
    // Note: The registered Firebase Installation ID is delivered to the
    // OnRegistrationReceived callback.
    LogMessage("Registered with FCM");
  }
});

גישה לטוקן הרישום של FCM (יצא משימוש)

שימו לב: התכונה הזו הוצאה משימוש. מומלץ להשתמש במזהי התקנה ב-Firebase, כי השיטה הזו תוסר בגרסה עתידית.

בזמן האתחול של ספריית Firebase Cloud Messaging, מתבצעת בקשה לטוקן רישום עבור מופע אפליקציית הלקוח. האפליקציה תקבל את האסימון באמצעות הקריאה החוזרת OnTokenReceived, שצריך להגדיר אותה במחלקה שמטמיעה את firebase::messaging::Listener.

כדי לטרגט את המופע הספציפי של האפליקציה, תצטרכו גישה לטוקן הזה.

הערה לגבי מסירת הודעות ב-Android

כשהאפליקציה לא פועלת בכלל ומשתמש מקיש על התראה, ההודעה לא מנותבת כברירת מחדל דרך הקריאות החוזרות המובנות של FCM. במקרה כזה, מטעני ההודעות מתקבלים דרך Intent שמשמש להפעלת האפליקציה. כדי ש-FCM יעביר את ההודעות הנכנסות האלה לקריאה החוזרת של ספריית C++‎, צריך לבטל את השיטה 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 יהיה null.

בקצרה:

מצב האפליקציה	התראה	נתונים	שניהם
חזית	OnMessageReceived	OnMessageReceived	OnMessageReceived
רקע	מגש המערכת	OnMessageReceived	התראה: מגש המערכת נתונים: בתוספות של הכוונה.

טיפול בהודעות מותאמות אישית ב-Android

כברירת מחדל, ההתראות שנשלחות לאפליקציה מועברות אל ::firebase::messaging::Listener::OnMessageReceived, אבל במקרים מסוימים כדאי לשנות את התנהגות ברירת המחדל. כדי לעשות את זה ב-Android, צריך לכתוב מחלקות מותאמות אישית שמרחיבות את com.google.firebase.messaging.cpp.ListenerService וגם לעדכן את AndroidManifest.xml של הפרויקט.

שינוי אמצעי התשלום ListenerService

‫ListenerService היא מחלקת Java שמיירטת הודעות נכנסות שנשלחות לאפליקציה ומנתבת אותן לספריית C++. כשהאפליקציה בחזית (או כשהיא ברקע ומקבלת מטען ייעודי (payload) של נתונים בלבד), ההודעות יעברו דרך אחת מהפונקציות החוזרות (callback) שסופקו במחלקה הזו. כדי להוסיף התנהגות מותאמת אישית לטיפול בהודעות, צריך להרחיב את 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 יש קובץ AndroidManifest.xml שמצהיר על ברירת המחדל של FCM ListenerService. המניפסט הזה בדרך כלל משולב עם המניפסט הספציפי לפרויקט, וכך ListenerService יכול לפעול. צריך להחליף את ListenerService בשירות המאזין המותאם אישית. כדי לעשות את זה, צריך להסיר את ברירת המחדל ListenerService ולהוסיף את השירות המותאם אישית. אפשר לעשות את זה באמצעות השורות הבאות בקובץ AndroidManifest.xml של הפרויקטים:

<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). כדי לעשות את זה, מוסיפים ערך של מטא-נתונים ל-Info.plist (ולא ל-GoogleService-Info.plist) בפלטפורמות של אפל, או ל-AndroidManifest.xml ב-Android:

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::SetRegistrationOnInitEnabled(true);

‫

הערה: SetTokenRegistrationOnInitEnabled הוצא משימוש. במקומו צריך להשתמש ב-SetRegistrationOnInitEnabled.

הערך הזה נשמר גם אחרי הפעלה מחדש של האפליקציה.

הודעות עם קישורי עומק ב-Android

‫FCM מאפשר לשלוח הודעות שמכילות קישור עומק לאפליקציה. כדי לקבל הודעות שמכילות קישור עומק, צריך להוסיף מסנן 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 הזה כדי לטפל בקישור.

השלבים הבאים

אחרי שמסיימים את שלבי ההגדרה, הנה כמה אפשרויות להמשך העבודה עם FCM עבור C++‎:

• שליחת הודעות למכשירים
• קבלת הודעות באפליקציית C++‎
• שליחת הודעות לנושאים