Başlama

Google Kullanıcı Mesajlaşma Platformu (UMP) SDK'sı, gizlilik seçeneklerini yönetmenize yardımcı olan bir gizlilik ve mesajlaşma aracıdır. Daha fazla bilgi için Gizlilik ve mesajlaşma hakkında başlıklı makaleyi inceleyin.

Ön koşullar

  • Android API düzeyi 21 veya sonraki sürümler (Android için)

Mesaj türü oluşturma

AdMob hesabınızın Gizlilik ve mesajlaşma sekmesinde bulunan Kullanılabilir kullanıcı mesajı türlerinden birini kullanarak kullanıcı mesajları oluşturun. UMP SDK'sı, projenizde ayarlanan AdMob uygulama kimliğinden oluşturulan bir gizlilik mesajını göstermeye çalışır.

Daha fazla bilgi için Gizlilik ve mesajlaşma hakkında bölümüne bakın.

SDK'yı yükleyin

  1. Google Mobile Ads (GMA) C++ SDK'sını yükleme adımlarını uygulayın. UMP C++ SDK'sı, GMA C++ SDK'sına dahildir.

  2. Devam etmeden önce projede uygulamanızın AdMob uygulama kimliğini yapılandırdığınızdan emin olun.

  3. Kodunuzda ConsentInfo::GetInstance() çağrısını yaparak UMP SDK'sını başlatın.

    • Android'de, NDK tarafından sağlanan JNIEnv ve Activity öğelerini iletmeniz gerekir. Bunu yalnızca GetInstance() numaralı telefonu ilk aradığınızda yapmanız gerekir.
    • Alternatif olarak, uygulamanızda zaten Firebase C++ SDK'sını kullanıyorsanız GetInstance() uygulamasını ilk kez aradığınızda bir firebase::App iletebilirsiniz.
    #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() için yapılan sonraki tüm çağrılar aynı örneği döndürür.

UMP SDK'sını kullanmayı bitirdiyseniz ConsentInfo örneğini silerek SDK'yı kapatabilirsiniz:

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

Eşzamansız işlemleri izlemek için Future kullanın

firebase::Future, eşzamansız yöntem çağrılarının tamamlanma durumunu belirlemenize olanak tanır.

Eşzamansız olarak çalışan tüm UMP C++ işlevleri ve yöntem çağrıları bir Future döndürür ve en son işlemden Future almak için bir "son sonuç" işlevi de sağlar.

Future öğesinden sonuç elde etmenin iki yolu vardır:

  1. İşlem tamamlandığında çağrılan kendi geri çağırma işlevinizi ileterek OnCompletion() öğesini çağırın.
  2. Future öğesinin status() öğesini düzenli olarak kontrol edin. Durum kFutureStatusPending yerine kFutureStatusCompleted olarak değiştiğinde işlem tamamlanmış demektir.

Asenkron işlem tamamlandıktan sonra, işlemin hata kodunu almak için Future'nın error() değerini kontrol etmeniz gerekir. Hata kodu 0 (kConsentRequestSuccess veya kConsentFormSuccess) ise işlem başarıyla tamamlanmış demektir. Aksi takdirde, hata kodunu ve error_message() simgesini kontrol ederek sorunun ne olduğunu belirleyin.

Tamamlama geri araması

Aşağıda, tamamlanma geri çağırma işlevi ayarlamak için OnCompletion işlevinin nasıl kullanılacağına dair bir örnek verilmiştir. Bu işlev, asenkron işlem tamamlandığında çağrılır.

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.
    }
  });
}

Döngü anketini güncelleme

Bu örnekte, uygulama başlatılırken başlatılan bir asynkron işlemden sonra sonuçlar başka bir yerde (her karede bir kez çalışan oyunun güncelleme döngüsü işlevinde) kontrol edilir.

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 hakkında daha fazla bilgi için Firebase C++ SDK dokümanlarına ve GMA C++ SDK dokümanlarına bakın.

İzin almak için aşağıdaki adımları uygulayın:

  1. En son kullanıcı rızası bilgilerini isteyin.
  2. Gerekirse bir izin formu yükleyip gösterin.

RequestConsentInfoUpdate() kullanarak her uygulama başlatıldığında kullanıcının izin bilgilerinin güncellenmesini istemeniz gerekir. Bu istek, aşağıdakileri kontrol eder:

  • İzin gerekip gerekmediği. Örneğin, ilk kez izin verilmesi gerekiyor veya önceki izin kararının süresi dolmuş.
  • Gizlilik seçenekleri giriş noktasının gerekli olup olmadığı. Bazı gizlilik mesajları, uygulamaların kullanıcıların gizlilik seçeneklerini istedikleri zaman değiştirmesine izin vermesini gerektirir.

Gerekirse gizlilik mesajı formu yükleyip gösterin

En güncel izin durumunu aldıktan sonra, kullanıcı iznini almak için gereken tüm formları yüklemek üzere LoadAndShowConsentFormIfRequired() işlevini çağırın. Formlar yüklendikten sonra hemen gösterilir.

Aşağıdaki kodda, kullanıcının en son izin bilgilerinin nasıl isteneceği gösterilmektedir. Gerekirse kod, bir gizlilik mesajı formu yükler ve gösterir:

#include "firebase/gma/ump.h"

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

Tamamlama geri çağırma işlevi yerine güncelleme döngüsü anketi kullanarak tamamlanma durumunu kontrol etme örneği için yukarıya bakın.

Kullanıcı bir seçim yaptıktan veya formu kapattıktan sonra herhangi bir işlem yapmanız gerekiyorsa bu mantığı, LoadAndShowConsentFormIfRequired() tarafından döndürülen Future değerini işleyen koda yerleştirin.

Gizlilik seçenekleri

Bazı gizlilik mesajı formları, yayıncı tarafından oluşturulan bir gizlilik seçenekleri giriş noktasından sunulur. Bu sayede kullanıcılar gizlilik seçeneklerini istedikleri zaman yönetebilir. Kullanıcılarınızın gizlilik seçenekleri giriş noktasında gördüğü mesaj hakkında daha fazla bilgi edinmek için Mevcut kullanıcı mesajı türleri bölümüne bakın.

Reklam isteğinde bulun

Uygulamanızda reklam istemeden önce ConsentInfo::GetInstance()‑> CanRequestAds() kullanarak kullanıcıdan izin alıp almadığınızı kontrol edin. İzin alınırken kontrol edilecek iki yer vardır:

  • Mevcut oturumda izin alındıktan sonra.
  • RequestConsentInfoUpdate()'ü aradıktan hemen sonra. İzin önceki oturumda alınmış olabilir. Gecikmeyle ilgili en iyi uygulama olarak, uygulamanız kullanıma sunulduktan sonra en kısa sürede reklam yüklemeye başlayabilmek için geri aramanın tamamlanmasını beklememenizi öneririz.
işlevini çağırana kadar ConsentInfo::GetInstance()‑> CanRequestAds() her zaman false döndürür.

İzin toplama işlemi sırasında hata meydana gelirse reklam isteyip isteyemeyeceğinizi kontrol etmeniz gerekir. UMP SDK'sı, önceki oturumdaki izin durumunu kullanır.

Aşağıdaki eksiksiz örnekte güncelleme döngüsü anketi kullanılmaktadır ancak asenkron işlemleri izlemek için OnCompletion geri çağırma işlevlerini de kullanabilirsiniz. Kod yapınıza en uygun tekniği kullanın.

#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 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;
      }
    }
  }
}

Test

Uygulamanızı geliştirirken entegrasyonu test etmek istiyorsanız test cihazınızı programatik olarak kaydettirmek için aşağıdaki adımları uygulayın. Uygulamanızı yayınlamadan önce bu test cihazı kimliklerini ayarlayan kodu kaldırdığınızdan emin olun.

  1. RequestConsentInfoUpdate() Hizmetleri İçin Arayın.

  2. Günlük çıkışında, cihaz kimliğinizi ve test cihazı olarak nasıl ekleyeceğinizi gösteren aşağıdaki örneğe benzer bir mesaj olup olmadığını kontrol edin:

    Yapay Zeka

    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. Test cihazınızın kimliğini panoya kopyalayın.

  4. ConsentRequestParameters.debug_settings.debug_device_ids değerini test cihazı kimliklerinizin listesine ayarlayacak şekilde kodunuzu değiştirin.

    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);
}

Coğrafi bölgeyi zorlama

UMP SDK'sı, debug_settings.debug_geography kullanarak uygulamanızın davranışını cihaz AEA veya Birleşik Krallık gibi çeşitli bölgelerdeymiş gibi test etmenizi sağlar. Hata ayıklama ayarlarının yalnızca test cihazlarında çalıştığını unutmayın.

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);
}

Uygulamanızı UMP SDK ile test ederken kullanıcıların ilk yükleme deneyimini simüle edebilmek için SDK'nın durumunu sıfırlamanız faydalı olabilir. SDK, bunu yapmak için Reset() yöntemini sağlar.

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