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ı 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 öğelerini iletmeniz 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 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ıldıysa firebase::kInitResultSuccess, uygulamanızda gerekli bağımlılıklardan herhangi biri eksikse firebase::kInitResultFailedMissingDependency döndürür. Bu hata oluştuğunda platformunuz için tüm yükleme adımlarını uyguladığınızdan emin olun.

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

Not: Kullanıcı Mesajlaşma Platformu SDK'sını başlatmadan önce Google Mobile Ads C++ SDK'sını başlatmanız gerekmez.

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'nin status() ayarlarını 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.

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

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.

Not: UMP C++ SDK'sında tüm asenkron işlemler firebase::Future<void> döndürür.

İzin toplama

İ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.

İzin bilgileri isteği

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ı 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.

Uyarı: İzin durumunu kontrol etmenin diğer yollarını (ör. uygulamanızdaki önbellek veya önceden kaydedilmiş bir izin dizesi) kullanmak, iznin süresi dolmuşsa TCF 3.3 hatasına neden olabilir.

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.

Önemli Nokta: Hiçbir gizlilik mesajı formunda reklam isteğinde bulunmadan önce kullanıcı izninin alınması gerekmiyorsa geri çağırma hemen çağrılır.

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.

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

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ırken kontrol edilmesi gereken 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.

Not: RequestConsentInfoUpdate()

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 tam ö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 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ö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'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();

Dikkat: Bu yöntemin yalnızca test amacıyla kullanılması amaçlanmıştır. Üretim kodunda Reset() çağrısı yapmamalısınız.