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 sekmesinin altında bulunan Mevcut 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 başlıklı makaleyi inceleyin.

SDK'yı yükleme

  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 sınavlarını geçmeniz gerekir. Bunu yalnızca GetInstance()'ü ilk kez aradığınızda yapmanız gerekir.
    • Alternatif olarak, uygulamanızda halihazırda Firebase C++ SDK'sını kullanıyorsanız GetInstance() işlevini ilk kez çağırdığı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 çağrıların tümü aynı örneği döndürür.

UMP SDK'sını kullanmayı bıraktıysanız 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 göndererek OnCompletion() işlevini ç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ıştır. Aksi takdirde, hatanın nedenini belirlemek için hata kodunu ve error_message() değerini kontrol edin.

Geri çağırmayı tamamlama

Aşağıda, eşzamansız işlem tamamlandığında çağrılan bir tamamlama geri çağırması ayarlamak için OnCompletion özelliğinin nasıl kullanılacağına dair bir örnek verilmiştir.

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 alınması gerekir veya önceki rıza kararının süresi dolmuş olabilir.
  • Gizlilik seçenekleri giriş noktası gerekip gerekmediği. Bazı gizlilik mesajları, uygulamaların kullanıcıların gizlilik seçeneklerini istedikleri zaman değiştirmelerine izin vermesini zorunlu kılar.

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 güncel izin bilgilerinin nasıl isteneceği gösterilmektedir. Gerekirse kod yüklenir ve bir gizlilik mesajı formu sunar.

#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 hangi mesajı gördüğü hakkında daha fazla bilgi edinmek için Kullanılabilir kullanıcı mesajı türleri bölümüne göz atı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ırken kontrol edilmesi gereken iki yer vardır:

  • Mevcut oturumda izin alındıktan sonra.
  • RequestConsentInfoUpdate() adlı kişiyi 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 sürecinde bir hata oluşursa reklam isteğinde bulunup bulunamayacağınızı yine de kontrol etmeniz gerekir. UMP SDK'sı önceki oturumdaki izin durumunu kullanır.

Aşağıdaki eksiksiz örnekte güncelleme döngüsü yoklaması kullanılmaktadır ancak eşzamansız işlemleri izlemek için OnCompletion geri çağırmalarını da kullanabilirsiniz. Kod yapınıza daha uygun olan 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 cihazınızı 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ı kimliğinizi panonuza 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ölgelerde bulunuyormuş gibi test etmeniz için bir yöntem sunar. 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'sıyla test ederken, kullanıcının ilk yükleme deneyimini simüle edebilmek için SDK'nın durumunu sıfırlamanın yararlı olabileceğini görebilirsiniz. SDK, bunu yapmak için Reset() yöntemini sağlar.

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