Google User Messaging Platform(UMP)SDK は、プライバシー設定の管理に役立つプライバシーとメッセージのツールです。詳しくは、 プライバシーとメッセージについてをご覧ください。
前提条件
- Android API レベル 21 以降(Android の場合)
メッセージ タイプを作成する
AdMob アカウントの [**プライバシーとメッセージ**] タブで、[利用可能なユーザー向けメッセージ タイプ]を使用してユーザー向けメッセージを作成します。UMP SDK は、プロジェクトで設定された AdMob アプリケーション ID から作成されたプライバシー メッセージを表示しようとします。
詳しくは、 プライバシーとメッセージについてをご覧ください。
SDK をインストールする
手順に沿って Firebase C++ SDK をインストールします。UMP C++ SDK は Firebase C++ SDK に含まれています。
続行する前に、プロジェクトで AdMob で収益化しているアプリの AdMob アプリ IDを設定していることを確認してください。
コードで、UMP SDK を呼び出して
ConsentInfo::GetInstance()初期化します。- Android では、NDK によって提供される
JNIEnvとActivityを渡す必要があります。これは、GetInstance()を初めて呼び出すときにのみ必要です。 - または、アプリで Firebase C++
SDK をすでに使用している場合は、
を初めて呼び出すときに
firebase::Appを渡すことができます。GetInstance()
#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- Android では、NDK によって提供される
ConsentInfo::GetInstance() を呼び出すと、常に同じインスタンスが返されます。
UMP SDK の使用が終了したら、ConsentInfo インスタンスを削除して SDK をシャットダウンできます。
void ShutdownUserMessagingPlatform() {
ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
delete consent_info;
}
Future を使用して非同期オペレーションをモニタリングする
A
firebase::Future
を使用すると、非同期メソッド
呼び出しの完了ステータスを特定できます。
非同期で動作するすべての UMP C++ 関数とメソッド呼び出しは Future を返します。また、最新のオペレーションから Future を取得する「前回の結果」関数も提供します。
Future から結果を取得する方法は 2 つあります。
OnCompletion()を呼び出して、独自のコールバック関数を渡します。この関数は、オペレーションが完了すると呼び出されます。Futureのstatus()を定期的に確認します。ステータスがkFutureStatusPendingからkFutureStatusCompletedに変わると、オペレーションは完了しています。
非同期オペレーションが完了したら、Future の error() を確認して、オペレーションのエラーコードを取得する必要があります。エラーコードが 0(kConsentRequestSuccess
または kConsentFormSuccess)の場合、オペレーションは正常に完了しています。それ以外の場合は、エラーコードと
error_message() を確認して、問題の原因を特定します。
完了コールバック
非同期オペレーションが完了したときに呼び出される完了コールバックを設定するために OnCompletion を使用する方法の例を次に示します。
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.
}
});
}
更新ループ ポーリング
この例では、アプリの起動時に非同期オペレーションが開始された後、結果はゲームの更新ループ関数(フレームごとに 1 回実行)で確認されます。
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 の詳細については、Firebase C++ SDK
のドキュメント
と GMA C++ SDK のドキュメントをご覧ください。
ユーザーの同意情報を取得する
アプリの起動ごとに、
を使用してユーザーの同意情報の更新をリクエストする必要があります。
RequestConsentInfoUpdate()このリクエストでは、次の点が確認されます。
- 同意が必要かどうか 。たとえば、初回のみ同意が必要な場合や、以前の同意の決定が期限切れになった場合などです。
- プライバシー オプションのエントリ ポイントが必要かどうか 。一部のプライバシー メッセージでは、ユーザーがいつでもプライバシー オプションを変更できるようにする必要があります。
#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.
});
}
プライバシー メッセージ フォームを読み込んで表示する
最新の同意ステータスを受け取ったら、
LoadAndShowConsentFormIfRequired() を呼び出して、ユーザーの同意を収集するために必要なフォームを読み込みます。読み込み後、フォームがすぐに表示されます。
#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.
}
});
}
});
}
完了コールバックではなく 更新ループ ポーリングを使用して完了を確認する例については、上記をご覧ください。
ユーザーが選択を行うかフォームを拒否した後になんらかの措置が必要な場合は、そのロジックを LoadAndShowConsentFormIfRequired() から返された Future を処理するコードに配置します。
プライバシー オプション
一部のプライバシー メッセージ フォームは、パブリッシャー レンダリングのプライバシー オプション エントリ ポイントから表示され、ユーザーはいつでもプライバシー オプションを管理できます。 プライバシー オプションのエントリ ポイントでユーザーに表示されるメッセージについて詳しくは、利用可能なユーザー向けメッセージ タイプをご覧ください。
ユーザーの同意を得て広告をリクエストする
広告をリクエストする前に、
ConsentInfo::GetInstance()‑>
CanRequestAds() を使用して、ユーザーから同意を得ているかどうかを
確認します。
同意を収集しながら広告をリクエストできるかどうかを確認する場所は次のとおりです。
- UMP SDK が現在のセッションで同意を収集した後。
RequestConsentInfoUpdate()を呼び出した直後。UMP SDK は、以前のアプリ セッションで同意を取得している可能性があります。
同意収集プロセス中にエラーが発生した場合は、広告をリクエストできるかどうかを確認します。UMP SDK は、以前のアプリ セッションの同意ステータスを使用します。
冗長な広告リクエスト作業を回避する
同意を収集した後と
RequestConsentInfoUpdate()を呼び出した後に
ConsentInfo::GetInstance()‑>
CanRequestAds()を確認する場合は、
両方のチェックでtrueが返される可能性がある冗長な広告リクエストをロジックで回避してください。たとえば、ブール変数を使用します。
次の完全な例では更新ループ ポーリングを使用していますが、コールバック
OnCompletionを使用して非同期オペレーションをモニタリングすることもできます。コード構造に適した手法を使用してください。
#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;
}
}
}
}
テスト
開発中にアプリでの統合をテストする場合は、次の手順に沿ってプログラムでテストデバイスを登録します。アプリをリリースする前に、テストデバイス ID を設定するコードを必ず削除してください。
RequestConsentInfoUpdate()を呼び出します。ログ出力で、次の例のようなメッセージを確認します。ここには、デバイス ID とテストデバイスとしてデバイスを追加する方法が示されています。
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]テストデバイスの ID をクリップボードにコピーします。
コードを変更して、
ConsentRequestParameters.debug_settings.debug_device_idsをテストデバイス ID のリストに設定します。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); }
地域を強制的に適用する
UMP SDK では、デバイスが欧州経済領域(EEA)、英国、スイスなどのさまざまな地域にあるかのようにアプリの動作をテストできます。
debug_settings.debug_geographyデバッグ設定はテスト用デバイスでのみ機能します。
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);
}
同意ステータスをリセットする
UMP SDK でアプリをテストする際、ユーザーの初回インストール エクスペリエンスをシミュレーションできるように、SDK の状態をリセットすると便利な場合があります。
SDK には、これを行うための Reset() メソッドが用意されています。
ConsentInfo::GetInstance()->Reset();