Başlama

Google Kullanıcı Mesajlaşma Platformu (UMP) SDK'sı, gizlilik tercihlerini 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 sekmesindeki Kullanılabilir kullanıcı mesajı türleri'nden birini kullanarak kullanıcı mesajları oluşturun. UMP SDK'sı, projenizde ayarlanan AdMob uygulama kimliğinden oluşturulan bir gizlilik mesajı 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. Firebase C++ SDK'sını yükleme adımlarını uygulayın. UMP C++ SDK'sı, Firebase C++ SDK'sına dahildir.

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

3. Kodunuzda ConsentInfo::GetInstance() yöntemini çağırarak UMP SDK'sını başlatın.

   • Android'de, NDK tarafından sağlanan JNIEnv ve Activity değerlerini iletmeniz gerekir. Bunu yalnızca GetInstance() numarasını ilk kez aradığınızda yapmanız gerekir.
   • Alternatif olarak, uygulamanızda Firebase C++ SDK'sını kullanıyorsanız GetInstance() yöntemini ilk kez çağırdığınızda bir firebase::App iletebilirsiniz.

   #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() için sonraki tüm çağrılar aynı örneği döndürür.

Not: GetInstance() yöntemlerinin isteğe bağlı bir firebase::InitResult çıkış parametresi vardır. Bu parametre, SDK başarıyla başlatılırsa firebase::kInitResultSuccess, uygulamanızda gerekli bağımlılıklar eksikse firebase::kInitResultFailedMissingDependency değerini döndürür. Bu hata oluşursa platformunuz için tüm yükleme adımlarını uyguladığınızdan emin olun.

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

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

Not: Kullanıcı Mesajlaşma Platformu SDK'sını ilk kullanıma hazırlamadan önce Firebase C++ SDK'sını ilk kullanıma hazırlamanız gerekmez.

Eşzamansız işlemleri izlemek için Future kullanma

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 değerini almak için bir "son sonuç" işlevi de sağlar.

Future öğesinden sonuç almanın iki yolu vardır:

1. İşlem tamamlandığında çağrılan kendi geri çağırma işlevinizi ileterek OnCompletion() işlevini çağırın.
2. Future cihazının status() değerini düzenli olarak kontrol edin. Durum kFutureStatusPending yerine kFutureStatusCompleted olduğunda işlem tamamlanmış demektir.

Eşzamansız işlem tamamlandıktan sonra işlemin hata kodunu almak için Future öğesinin error() değerini kontrol etmeniz gerekir. Hata kodu 0 (kConsentRequestSuccess veya kConsentFormSuccess) ise işlem başarıyla tamamlanmıştır. Aksi takdirde, sorunun ne olduğunu belirlemek için hata kodunu ve error_message() değerini kontrol edin.

Not: RequestConsentInfoUpdate() tarafından döndürülen hata kodu, ConsentRequestError enum'unu kullanır; diğer tüm işlemler ConsentFormError kullanır.

Tamamlanma geri çağırması

Aşağıda, eşzamansız işlem tamamlandığında çağrılan bir tamamlama geri çağırma işlevi ayarlamak için OnCompletion öğesinin 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.
    }
  });
}

Güncelleme döngüsü yoklaması

Bu örnekte, uygulama başlatıldığında eşzamansız bir işlem başlatıldıktan sonra sonuçlar başka bir yerde, oyunun güncelleme döngüsü işlevinde (kare başına bir kez çalışır) 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 belgelerini ve GMA C++ SDK belgelerini inceleyin.

Not: UMP C++ SDK'sında tüm eşzamansız işlemler firebase::Future<void> değerini döndürür.

Kullanıcının izin bilgilerini alma

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ı gerektiğinde veya önceki izin kararının süresi dolduğunda.
• 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ştirmelerine izin vermesini gerektirir.

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

Uyarı: İzin durumunu başka bir yöntemle (ör. uygulamanızdaki önbellek veya önceden kaydedilmiş bir izin dizesi) kontrol etmenizi önermiyoruz. Bu yöntemler, güncel olmayan kullanıcı rızası verileri döndürebilir.

Gizlilik mesajı formunu yükleme ve sunma

En güncel izin durumunu aldıktan sonra, kullanıcı izni almak için gereken formları yüklemek üzere LoadAndShowConsentFormIfRequired() yöntemini çağırın. Yüklendikten sonra formlar hemen gösterilir.

Önemli nokta: Reklam isteğinde bulunmadan önce kullanıcı rızasının alınmasını gerektiren gizlilik mesajı formu yoksa geri çağırma hemen çağrılır.

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

Tamamlanma geri çağırması yerine güncelleme döngüsü yoklaması kullanarak tamamlanma durumunu kontrol etme örneği için yukarıya bakın.

Not: Platforma bağlı olarak, FormParent bir Android Activity için JNI jobject referansı veya bir iOS UIViewController için işaretçidir ve FormParent türüne dönüştürülür.

Kullanıcı 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. Böylece kullanıcılar gizlilik seçeneklerini diledikleri zaman yönetebilir. Kullanıcılarınızın gizlilik seçenekleri giriş noktasında hangi mesajı göreceği hakkında daha fazla bilgi edinmek için Mevcut kullanıcı mesajı türleri başlıklı makaleyi inceleyin.

Kullanıcı rızasıyla reklam isteğinde bulunma

Reklam isteğinde bulunmadan önce ConsentInfo::GetInstance()‑> CanRequestAds() kullanarak kullanıcıdan izin alıp almadığınızı kontrol edin:

Rıza toplarken reklam isteğinde bulunup bulunamayacağınızı kontrol etmek için aşağıdaki yerlere bakabilirsiniz:

• UMP SDK'sı mevcut oturumda izin aldıktan sonra.
• RequestConsentInfoUpdate() yöntemini çağırdıktan hemen sonra. UMP SDK, önceki uygulama oturumunda izin almış olabilir.

Önemli: ConsentInfo::GetInstance()‑> CanRequestAds(), siz RequestConsentInfoUpdate() yöntemini çağırana kadar her zaman false değerini döndürür.

Rıza alma işlemi sırasında bir hata oluşursa reklam isteyip isteyemeyeceğinizi kontrol edin. UMP SDK'sı, önceki uygulama oturumundaki izin durumunu kullanır.

Gereksiz reklam isteği işlemlerini önleme

İzin aldıktan ve RequestConsentInfoUpdate() yöntemini çağırdıktan sonra ConsentInfo::GetInstance()‑> CanRequestAds() yöntemini kontrol ederken mantığınızın, her iki kontrolün de true döndürmesine neden olabilecek gereksiz reklam isteklerini engellediğinden emin olun. Örneğin, boole değişkeniyle.

Aşağıdaki eksiksiz örnekte güncelleme döngüsü yoklaması kullanılmaktadır ancak eşzamansız işlemleri izlemek için geri çağırmaları da kullanabilirsinizOnCompletion. Kod yapınıza daha uygun olan tekniği kullanın.

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

Test

Uygulamanızı geliştirirken entegrasyonu test etmek istiyorsanız test cihazınızı programatik olarak kaydetmek 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, aşağıdaki örneğe benzer bir mesaj olup olmadığını kontrol edin. Bu mesajda cihaz kimliğiniz ve cihazınızı test cihazı olarak nasıl ekleyeceğiniz gösterilir:

   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. Test cihazı kimliğinizi panonuza kopyalayın.

4. Kodunuzu, ConsentRequestParameters.debug_settings.debug_device_ids değerini test cihazı kimliklerinizin listesi olarak ayarlayacak şekilde 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 konumu zorunlu kılma

UMP SDK'sı, debug_settings.debug_geography kullanarak uygulamanızın davranışını cihaz Avrupa Ekonomik Alanı (AEA), Birleşik Krallık ve İsviçre 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);
}

İzin durumunu sıfırlama

Uygulamanızı UMP SDK ile test ederken, kullanıcının ilk yükleme deneyimini simüle edebilmek için SDK'nın durumunu sıfırlamanın faydalı olabileceğini görebilirsiniz. SDK, bu işlem için Reset() yöntemini sağlar.

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

Dikkat: Bu yöntem yalnızca test amaçlı kullanılmak üzere tasarlanmıştır. Üretim kodunda Reset() yöntemini çağırmamalısınız.