שנתחיל?

בהתאם למדיניות Google בנושא הסכמת משתמשים באיחוד האירופי, עליכם להציג הודעות גילוי נאות מסוימות למשתמשים שנמצאים באזור הכלכלי האירופי (EEA) ובבריטניה. בנוסף, אתם צריכים לקבל את הסכמתם לשימוש בקובצי cookie או באמצעים אחרים לאחסון מקומי, כשהדבר נדרש על פי חוק, ולשימוש במידע אישי (כמו מזהה פרסום) כדי להציג מודעות. המדיניות הזו משקפת את הדרישות שמפורטות ב-ePrivacy Directive (הדירקטיבה בנושא פרטיות ותקשורת אלקטרונית) וב-General Data Protection Regulation (התקנה הכללית להגנה על מידע, GDPR) של האיחוד האירופי.

כדי לעזור לבעלי אפליקציות למלא את החובות שלהם במסגרת המדיניות הזו, Google מציעה את User Messaging Platform (UMP) SDK. UMP SDK עודכן כדי לתמוך בתקנים העדכניים ביותר של IAB. מעכשיו אפשר לטפל בכל ההגדרות האלו בקלות, ב AdMob פרטיות והודעות.

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

• מבצעים את ההוראות במדריך לתחילת העבודה.

• Android API ברמה 21 ואילך (ל-Android)

• אם אתם עובדים על דרישות שקשורות ל-GDPR, כדאי לקרוא את המאמר איך הדרישות של IAB משפיעות על הודעות בנושא הסכמה באיחוד האירופי

איך יוצרים את סוג ההודעה

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

לפרטים נוספים, ראו מידע על פרטיות והודעות.

התקנת ה-SDK

1. פועלים לפי השלבים להתקנת Google Mobile Ads (GMA) C++ SDK. UMP C++ SDK כלול ב-GMA C++ SDK.

2. לפני שממשיכים, חשוב לוודא שמגדירים את מזהה האפליקציה של האפליקציה ב-AdMob בפרויקט.

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

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

   #include "firebase/gma/ump.h"
   
   namespace ump = ::firebase::gma::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() יחזירו את אותו מופע.

הערה: ל-methods GetInstance() יש פרמטר פלט אופציונלי של firebase::InitResult, שמחזיר firebase::kInitResultSuccess אם ה-SDK הופעל בהצלחה, או firebase::kInitResultFailedMissingDependency אם חסרים יחסי תלות נדרשים באפליקציה. במקרה של השגיאה הזו, חשוב לוודא שביצעתם את כל שלבי ההתקנה של הפלטפורמה.

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

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

הערה: אין צורך להפעיל את C++ SDK של מודעות Google לנייד לפני שמתחילים באתחול של User Messaging Platform SDK.

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

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

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

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

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

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

הערה: קוד השגיאה שמוחזר על ידי RequestConsentInfoUpdate() משתמש ב-enum ConsentRequestError; כל שאר הפעולות משתמשות ב-ConsentFormError.

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

זוהי דוגמה לשימוש ב-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.

הערה: ב-UMP C++ SDK, כל הפעולות האסינכרוניות מחזירות firebase::Future<void>.

בקשה למידע על הסכמה

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

#include "firebase/gma/ump.h"

namespace ump = ::firebase::gma::ump;

void MyApplicationStart() {
  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>& result) {
      if (result.error() != ump::kConsentRequestSuccess) {
        LogMessage("Error requesting consent update: %s", result.error_message());
      } else {
        // Consent status is now available.
      }
    });
}

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

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

טעינה והצגה של טופס הסכמה, לפי הצורך

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

הערה: בהתאם לפלטפורמה, FormParent הוא אזכור JNI jobject של Android Activity או מצביע אל iOS UIViewController, שמועבר לסוג FormParent.

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 consent form: %s", form_result.error_message());
          } else {
            // Either the form was shown and completed by the user, or consent was not required.
          }
        });
      }
    });
}

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

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

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

1. אחרי שהתקבלה הסכמה בסשן הנוכחי.
2. מיד לאחר שהתקשרת אל RequestConsentInfoUpdate(). ייתכן שהתקבלה הסכמה בסשן הקודם. כשיטה מומלצת לזמן אחזור מומלץ לא להמתין לסיום הקריאה החוזרת כדי שאפשר יהיה להתחיל לטעון מודעות בהקדם האפשרי אחרי השקת האפליקציה.

הערה: ConsentInfo::GetInstance()‑>CanRequestAds() מחזירה תמיד false עד שמתקשרים RequestConsentInfoUpdate()

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

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

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

namespace gma = ::firebase::gma;
namespace ump = ::firebase::gma::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 consent 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;
      }
    }
  }
}

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

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

לשם כך:

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

בדיקה

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

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

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

   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]
   

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

4. משנים את הקוד כדי להגדיר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);
   }
   

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

באמצעות UMP SDK אפשר לבדוק את התנהגות האפליקציה כאילו המכשיר נמצא ב-EEA או בבריטניה באמצעות ConsentRequestParameters.debug_settings.debug_geography. שימו לב שהגדרות ניפוי הבאגים פועלות רק במכשירי בדיקה.

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 מספק את Reset() השיטה לעשות זאת.

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

זהירות: השיטה הזו מיועדת למטרות בדיקה בלבד. אין לקרוא ל- Reset() בקוד של סביבת הייצור.