Başlayın

Google AB Kullanıcı Rızası Politikası uyarınca, Avrupa Ekonomik Alanı (AEA) ve Birleşik Krallık'taki kullanıcılarınıza belirli açıklamalar yapmanız ve yasal olarak gerekli olduğu durumlarda çerez veya başka yerel depolama bilgilerinin kullanımının yanı sıra kişisel verilerin (AdID) reklam yayınlamak amacıyla kullanılması için kullanıcıların iznini almanız gerekir. Bu politika AB eGizlilik Yönergesi ve Genel Veri Koruma Yönetmeliği (GDPR) gereksinimlerini yansıtmaktadır.

Google, yayıncıları bu politika kapsamındaki şartları yerine getirmeleri konusunda desteklemek amacıyla Kullanıcı Mesajlaşma Platformu (UMP) SDK'sını sunmaktadır. UMP SDK'sı, en son IAB standartlarını destekleyecek şekilde güncellenmiştir. Artık bu yapılandırmaların hepsi, AdMob gizlilik ve mesajlaşma bölümünden kullanılabilir.

Ön koşullar

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

Mesaj türü oluşturma

Mevcut kullanıcı mesajı türlerinden birini kullanarak kullanıcı mesajları oluşturun AdMob hesabınızdaki Gizlilik ve mesajlaşma UMP SDK'sı, projenizde ayarlanan AdMob Uygulama Kimliği'nden oluşturulan bir kullanıcı mesajını göstermeye çalışır. Uygulamanız için herhangi bir mesaj yapılandırılmamışsa SDK hata döndürür.

Daha fazla bilgi için Gizlilik ve mesajlaşma hakkında başlıklı makaleyi inceleyin.

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ı 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() 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 çağrıların tümü 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 belirleyebileceğiniz bir yöntem sunar.

Eşzamansız olarak çalışan tüm UMP C++ işlevleri ve yöntem çağrıları, Future döndürür ve ayrıca Future öğesini en son işlemden almak için bir "son sonuç" işlevi 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() öğesini çağırın.
  2. Future öğesinin status() öğesini düzenli olarak kontrol edin. kFutureStatusPending olan durum kFutureStatusCompleted olarak değiştiğinde işlem tamamlanmıştır.

Eşzamansız işlem tamamlandıktan sonra, işlemin hata kodunu almak için Future öğesinin error() öğesini 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.

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ü yoklamayı güncelle

Bu örnekte, uygulama başlatılırken 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'sı belgelerini ve GMA C++ SDK'sı belgelerini inceleyin.

RequestConsentInfoUpdate()kullanarak her uygulama lansmanında kullanıcının rıza bilgilerinin güncellenmesini istemelisiniz. Bu sayede, kullanıcınız henüz yapmadıysa veya izninin süresi dolduysa izin vermesi gerekip gerekmediğini belirleyebilirsiniz.

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

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

Gerekirse bir izin formu yükleyip gösterin

En güncel izin durumunu aldıktan sonra izin formu yüklemek için sınıfaLoadAndShowConsentFormIfRequired() ConsentInfo ulaşın. İzin durumu gerekliyse SDK bir form yükler ve sağlanan FormParentbölümünden hemen gösterir. Form kapatıldıktan sonra Future tamamlanır . Rıza gerekmiyorsa Future tamamlanır hemen çağrılır.

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

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

Reklam isteğinde bulun

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

  1. Mevcut oturumda izin alındıktan sonra.
  2. RequestConsentInfoUpdate()adlı kişiyi aramanızın hemen ardından. Önceki oturumda izin alınmış olabilir. Gecikmeyle ilgili en iyi uygulamalardan biri olarak, geri çağırma işleminin tamamlanmasını beklememenizi öneririz. Böylece, uygulamanız kullanıma sunulduktan hemen sonra reklamları yüklemeye başlayabilirsiniz.

İzin toplama sürecinde bir hata oluşursa yine de reklam isteğinde bulunmanız 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 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;
      }
    }
  }
}

Gizlilik seçenekleri

Bazı izin formlarında, kullanıcının istediği zaman iznini değiştirmesi gerekir. Gerekirse gizlilik seçenekleri düğmesi uygulamak için aşağıdaki adımları uygulayın.

Bunu yapabilmek için:

  1. Uygulamanızın ayarlar sayfasındaki bir düğme gibi, gizlilik seçenekleri formunu tetikleyebilecek bir kullanıcı arayüzü öğesi uygulayın.
  2. LoadAndShowConsentFormIfRequired() Tamamladıktan sonra, gizlilik seçenekleri formunu gösterebilecek kullanıcı arayüzü öğesinin gösterilip gösterilmeyeceğini belirlemek içingetPrivacyOptionsRequirementStatus() kontrol edin.
  3. Bir kullanıcı, kullanıcı arayüzü öğenizle etkileşime geçtiğinde formun gösterilmesi içinshowPrivacyOptionsForm() çağrısı yapın. Böylece kullanıcının gizlilik seçeneklerini istediği zaman güncelleyebilir.

Test

Geliştirme sürecinde uygulamanızdaki entegrasyonu test etmek istiyorsanız test cihazınızı programatik olarak kaydetmek için bu adımları uygulayın. Uygulamanızı yayınlamadan önce bu test cihazı kimliklerini oluşturan kodu kaldırdığınızdan emin olun.

  1. RequestConsentInfoUpdate()numaralı telefonu 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:

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

  4. Kodu, test cihazı kimliklerinizin listesini ConsentRequestParameters.debug_settings.debug_device_ids ayarlayıp 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);
}

Bir coğrafi bölgeyi zorunlu kılın

UMP SDK'sı, ConsentRequestParameters.debug_settings.debug_geographykullanarak cihaz AEA veya Birleşik Krallık'ta bulunuyormuş gibi uygulamanızın davranışını test etmenin bir yolunu 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();