‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

מתחילים

‫Google User Messaging Platform (UMP) SDK הוא כלי לניהול פרטיות ובקשות הסכמה שעוזר לכם לנהל את העדפות הפרטיות של המשתמשים. מידע נוסף זמין במאמר מידע על הכלי "פרטיות והודעות".

דרישות מוקדמות

‫Android API ברמת API 21 ומעלה (ל-Android)

יצירת סוג הודעה

יוצרים הודעות למשתמשים באמצעות אחד מסוגי ההודעות הזמינים למשתמשים בכרטיסייה פרטיות והודעות בחשבון AdMob. ערכת ה-UMP SDK מנסה להציג הודעה בנושא פרטיות שנוצרה ממזהה האפליקציה ב-AdMob שהוגדר בפרויקט.

פרטים נוספים זמינים במאמר מידע על הכלי "פרטיות והודעות".

התקנת ה-SDK

פועלים לפי השלבים להתקנת Firebase C++ SDK. ‫UMP C++ SDK כלול ב-Firebase C++ SDK.
חשוב לוודא שמגדירים בפרויקט את מזהה האפליקציה שמקושרת ל-AdMob לפני שממשיכים.

בקוד, מפעילים את ה-UMP SDK באמצעות קריאה ל-ConsentInfo::GetInstance().

ב-Android, צריך להעביר את JNIEnv ו-Activity שסופקו על ידי ה-NDK. צריך לעשות את זה רק בפעם הראשונה שמתקשרים אל GetInstance().
לחלופין, אם אתם כבר משתמשים ב-Firebase C++ SDK באפליקציה, אתם יכולים להעביר firebase::App בפעם הראשונה שאתם קוראים ל-GetInstance().

#include "firebase/ump/ump.h"

namespace ump = ::firebase::ump;

// Initialize using a firebase::App
void InitializeUserMessagingPlatform(const firebase::App& app) {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance(app);
}

// Initialize without a firebase::App
#ifdef ANDROID
void InitializeUserMessagingPlatform(JNIEnv* jni_env, jobject activity) {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance(jni_env, activity);
}
#else  // non-Android
void InitializeUserMessagingPlatform() {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
}
#endif

כל הקריאות הבאות ל-ConsentInfo::GetInstance() מחזירות את אותו מופע.

אם סיימתם להשתמש ב-UMP SDK, אתם יכולים לסגור את ה-SDK על ידי מחיקת המכונה של ConsentInfo:

void ShutdownUserMessagingPlatform() {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
  delete consent_info;
}

שימוש ב-`Future` למעקב אחרי פעולות אסינכרוניות

firebase::Future מאפשר לכם לקבוע את סטטוס ההשלמה של קריאות ל-method אסינכרוני.

כל הפונקציות והפעלות ה-method של UMP C++‎ שפועלות באופן אסינכרוני מחזירות Future, וגם מספקות פונקציה של "תוצאה אחרונה" כדי לאחזר את ה-Future מהפעולה האחרונה.

יש שתי דרכים לקבל תוצאה מ-Future:

מפעילים את הפונקציה OnCompletion() ומעבירים את פונקציית הקריאה החוזרת (callback) שלכם, שמופעלת כשהפעולה מסתיימת.
בודקים מדי פעם את status() של Future. כשהערך של status משתנה מ-kFutureStatusPending ל-kFutureStatusCompleted, הפעולה הושלמה.

אחרי שהפעולה האסינכרונית מסתיימת, צריך לבדוק את השדה error() של Future כדי לקבל את קוד השגיאה של הפעולה. אם קוד השגיאה הוא 0 (kConsentRequestSuccess או kConsentFormSuccess), הפעולה הושלמה בהצלחה. אחרת, בודקים את קוד השגיאה ואת error_message() כדי להבין מה השתבש.

קריאה חוזרת (callback) להשלמה

דוגמה לשימוש ב-OnCompletion כדי להגדיר קריאה חוזרת (callback) להשלמה, שנקראת כשהפעולה האסינכרונית מסתיימת.

void MyApplicationStart() {
  // [... other app initialization code ...]

  ump::ConsentInfo *consent_info = ump::ConsentInfo::GetInstance();

  // See the section below for more information about RequestConsentInfoUpdate.
  firebase::Future<void> result = consent_info->RequestConsentInfoUpdate(...);

  result.OnCompletion([](const firebase::Future<void>& req_result) {
    if (req_result.error() == ump::kConsentRequestSuccess) {
      // Operation succeeded. You can now call LoadAndShowConsentFormIfRequired().
    } else {
      // Operation failed. Check req_result.error_message() for more information.
    }
  });
}

עדכון סקר לולאה

בדוגמה הזו, אחרי שפעולה אסינכרונית מתחילה בהפעלת האפליקציה, התוצאות נבדקות במקום אחר, בפונקציית לולאת העדכון של המשחק (שפועלת פעם אחת בכל פריים).

ump::ConsentInfo *g_consent_info = nullptr;
bool g_waiting_for_request = false;

void MyApplicationStart() {
  // [... other app initialization code ...]

  g_consent_info = ump::ConsentInfo::GetInstance();
  // See the section below for more information about RequestConsentInfoUpdate.
  g_consent_info->RequestConsentInfoUpdate(...);
  g_waiting_for_request = true;
}

// Elsewhere, in the game's update loop, which runs once per frame:
void MyGameUpdateLoop() {
  // [... other game logic here ...]

  if (g_waiting_for_request) {
    // Check whether RequestConsentInfoUpdate() has finished.
    // Calling "LastResult" returns the Future for the most recent operation.
    firebase::Future<void> result =
      g_consent_info->RequestConsentInfoUpdateLastResult();

    if (result.status() == firebase::kFutureStatusComplete) {
      g_waiting_for_request = false;
      if (result.error() == ump::kConsentRequestSuccess) {
        // Operation succeeded. You can call LoadAndShowConsentFormIfRequired().
      } else {
        // Operation failed. Check result.error_message() for more information.
      }
    }
  }
}

מידע נוסף על firebase::Future זמין במסמכי התיעוד של Firebase C++ SDK ובמסמכי התיעוד של GMA C++ SDK.

קבלת פרטי ההסכמה של המשתמש

בכל פעם שהאפליקציה מופעלת, צריך לבקש עדכון של פרטי ההסכמה של המשתמש באמצעות RequestConsentInfoUpdate(). הבקשה הזו בודקת את הדברים הבאים:

אם נדרשת הסכמה. לדוגמה, אם נדרשת הסכמה בפעם הראשונה, או אם פג התוקף של החלטת ההסכמה הקודמת.
אם נדרשת נקודת כניסה לאפשרויות הפרטיות. בחלק מההודעות בנושא פרטיות, האפליקציות נדרשות לאפשר למשתמשים לשנות את אפשרויות הפרטיות שלהם בכל שלב.

#include "firebase/ump/ump.h"

namespace ump = ::firebase::ump;

void MyApplicationStart(ump::FormParent parent) {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();

  // Create a ConsentRequestParameters struct..
  ump::ConsentRequestParameters params;
  // Set tag for under age of consent. False means users are NOT under age of consent.
  params.tag_for_under_age_of_consent = false;

  consent_info->RequestConsentInfoUpdate(params).OnCompletion(
    [*](const Future<void>& req_result) {
      if (req_result.error() != ump::kConsentRequestSuccess) {
        // req_result.error() is a kConsentRequestError enum.
        LogMessage("Error requesting consent update: %s", req_result.error_message());
      }
      // Consent information is successfully updated.
    });
}

טוענים ומציגים את טופס ההודעה בנושא פרטיות

אחרי שמקבלים את סטטוס ההסכמה העדכני ביותר, קוראים ל-LoadAndShowConsentFormIfRequired() כדי לטעון את הטפסים שנדרשים לאיסוף הסכמה מהמשתמשים. אחרי שהטפסים נטענים, הם מוצגים מיד.

#include "firebase/ump/ump.h"

namespace ump = ::firebase::ump;

void MyApplicationStart(ump::FormParent parent) {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();

  // Create a ConsentRequestParameters struct..
  ump::ConsentRequestParameters params;
  // Set tag for under age of consent. False means users are NOT under age of consent.
  params.tag_for_under_age_of_consent = false;

  consent_info->RequestConsentInfoUpdate(params).OnCompletion(
    [*](const Future<void>& req_result) {
      if (req_result.error() != ump::kConsentRequestSuccess) {
        // req_result.error() is a kConsentRequestError enum.
        LogMessage("Error requesting consent update: %s", req_result.error_message());
      } else {
        consent_info->LoadAndShowConsentFormIfRequired(parent).OnCompletion(
        [*](const Future<void>& form_result) {
          if (form_result.error() != ump::kConsentFormSuccess) {
            // form_result.error() is a kConsentFormError enum.
            LogMessage("Error showing privacy message form: %s", form_result.error_message());
          } else {
            // Either the form was shown and completed by the user, or consent was not required.
          }
        });
      }
    });
}

למעלה מופיעה דוגמה לבדיקת השלמה באמצעות דגימת לולאת עדכון במקום קריאה חוזרת (callback) להשלמה.

אם אתם צריכים לבצע פעולות כלשהן אחרי שהמשתמש בחר אפשרות או סגר את הטופס, הוסיפו את הלוגיקה הזו לקוד שמטפל ב-Future שמוחזר על ידי LoadAndShowConsentFormIfRequired().

אפשרויות פרטיות

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

בקשת מודעות עם הסכמה מהמשתמשים

לפני ששולחים בקשות להצגת מודעות, משתמשים ב-ConsentInfo::GetInstance()‑> CanRequestAds() כדי לבדוק אם קיבלתם הסכמה מהמשתמש:

ריכזנו כאן את המקומות שבהם אפשר לבדוק אם אפשר לבקש מודעות בזמן איסוף ההסכמה:

אחרי ש-UMP SDK אוסף את ההסכמה בסשן הנוכחי.
מיד אחרי שמפעילים את RequestConsentInfoUpdate(). יכול להיות שה-UMP SDK קיבל הסכמה בסשן הקודם באפליקציה.

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

מניעת עבודה מיותרת של בקשות להצגת מודעות

כשבודקים את ConsentInfo::GetInstance()‑> CanRequestAds() אחרי איסוף ההסכמה ואחרי קריאה ל-RequestConsentInfoUpdate(), חשוב לוודא שהלוגיקה מונעת בקשות מיותרות להצגת מודעות שעלולות לגרום לכך ששתי הבדיקות יחזירו את הערך true. לדוגמה, באמצעות משתנה בוליאני.

בדוגמה הפתורה הבאה משתמשים בדגימה של לולאת עדכון, אבל אפשר גם להשתמש בקריאות חוזרות (callbacks) של OnCompletion כדי לעקוב אחרי פעולות אסינכרוניות. השתמשו בשיטה שמתאימה יותר למבנה הקוד שלכם.

#include "firebase/future.h"
#include "firebase/gma/gma.h"
#include "firebase/ump/ump.h"

namespace gma = ::firebase::gma;
namespace ump = ::firebase::ump;
using firebase::Future;

ump::ConsentInfo* g_consent_info = nullptr;
// State variable for tracking the UMP consent flow.
enum { kStart, kRequest, kLoadAndShow, kInitGma, kFinished, kErrorState } g_state = kStart;
bool g_ads_allowed = false;

void MyApplicationStart() {
  g_consent_info = ump::ConsentInfo::GetInstance(...);

  // Create a ConsentRequestParameters struct..
  ump::ConsentRequestParameters params;
  // Set tag for under age of consent. False means users are NOT under age of consent.
  params.tag_for_under_age_of_consent = false;

  g_consent_info->RequestConsentInfoUpdate(params);
  // CanRequestAds() can return a cached value from a previous run immediately.
  g_ads_allowed = g_consent_info->CanRequestAds();
  g_state = kRequest;
}

// This function runs once per frame.
void MyGameUpdateLoop() {
  // [... other game logic here ...]

  if (g_state == kRequest) {
    Future<void> req_result = g_consent_info->RequestConsentInfoUpdateLastResult();

    if (req_result.status() == firebase::kFutureStatusComplete) {
      g_ads_allowed = g_consent_info->CanRequestAds();
      if (req_result.error() == ump::kConsentRequestSuccess) {
        // You must provide the FormParent (Android Activity or iOS UIViewController).
        ump::FormParent parent = GetMyFormParent();
        g_consent_info->LoadAndShowConsentFormIfRequired(parent);
        g_state = kLoadAndShow;
      } else {
        LogMessage("Error requesting consent status: %s", req_result.error_message());
        g_state = kErrorState;
      }
    }
  }
  if (g_state == kLoadAndShow) {
    Future<void> form_result = g_consent_info->LoadAndShowConsentFormIfRequiredLastResult();

    if (form_result.status() == firebase::kFutureStatusComplete) {
      g_ads_allowed = g_consent_info->CanRequestAds();
      if (form_result.error() == ump::kConsentRequestSuccess) {
        if (g_ads_allowed) {
          // Initialize GMA. This is another asynchronous operation.
          firebase::gma::Initialize();
          g_state = kInitGma;
        } else {
          g_state = kFinished;
        }
        // Optional: shut down the UMP SDK to save memory.
        delete g_consent_info;
        g_consent_info = nullptr;
      } else {
        LogMessage("Error displaying privacy message form: %s", form_result.error_message());
        g_state = kErrorState;
      }
    }
  }
  if (g_state == kInitGma && g_ads_allowed) {
    Future<gma::AdapterInitializationStatus> gma_future = gma::InitializeLastResult();

    if (gma_future.status() == firebase::kFutureStatusComplete) {
      if (gma_future.error() == gma::kAdErrorCodeNone) {
        g_state = kFinished;
        // TODO: Request an ad.
      } else {
        LogMessage("Error initializing GMA: %s", gma_future.error_message());
        g_state = kErrorState;
      }
    }
  }
}

בדיקה

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

התקשרו אל RequestConsentInfoUpdate().

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

Android

Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231")
to set this as a debug device.

iOS

<UMP SDK>To enable debug mode for this device,
set: UMPDebugSettings.testDeviceIdentifiers = @[2077ef9a63d2b398840261c8221a0c9b]

מעתיקים את מזהה מכשיר הבדיקה ללוח.

משנים את הקוד כדי להגדיר את ConsentRequestParameters.debug_settings.debug_device_ids לרשימה של מזהי מכשירי הבדיקה.

void MyApplicationStart() {
  ump::ConsentInfo consent_info = ump::ConsentInfo::GetInstance(...);

  ump::ConsentRequestParameters params;
  params.tag_for_under_age_of_consent = false;
  params.debug_settings.debug_device_ids = {"TEST-DEVICE-HASHED-ID"};

  consent_info->RequestConsentInfoUpdate(params);
}

אילוץ מיקום גיאוגרפי

באמצעות debug_settings.debug_geography, ערכת ה-UMP SDK מאפשרת לבדוק את ההתנהגות של האפליקציה כאילו המכשיר נמצא באזורים שונים, כמו האזור הכלכלי האירופי (EEA), בריטניה ושווייץ. חשוב לזכור שהגדרות ניפוי הבאגים פועלות רק במכשירי בדיקה.

void MyApplicationStart() {
  ump::ConsentInfo consent_info = ump::ConsentInfo::GetInstance(...);

  ump::ConsentRequestParameters params;
  params.tag_for_under_age_of_consent = false;
  params.debug_settings.debug_device_ids = {"TEST-DEVICE-HASHED-ID"};
  // Geography appears as EEA for debug devices.
  params.debug_settings.debug_geography = ump::kConsentDebugGeographyEEA

  consent_info->RequestConsentInfoUpdate(params);
}

איפוס מצב ההסכמה

כשבודקים את האפליקציה באמצעות ה-UMP SDK, כדאי לאפס את מצב ה-SDK כדי לדמות את חוויית ההתקנה הראשונה של המשתמש. כדי לעשות את זה, ה-SDK מספק את ה-method‏ Reset().

  ConsentInfo::GetInstance()->Reset();