このページは Cloud Translation API によって翻訳されました。

始める

Google の EU ユーザーの同意ポリシーに基づき、広告主様は、欧州経済領域（EEA）および英国のユーザーに対して特定の開示を行い、法律で義務付けられている場合に Cookie またはその他のローカルストレージを使用すること、および広告配信に個人データ（AdID など）を使用することについてユーザーの同意を得る必要があります。このポリシーには、EU の e プライバシー指令と一般データ保護規則（GDPR）の要件が反映されています。

パブリッシャー様がこのポリシーで定められた義務を遂行できるよう、Google は User Messaging Platform（UMP）SDK を提供しています。最新の IAB 標準に対応するように UMP SDK が更新されました。これらの設定はすべて、[プライバシーとメッセージ] で AdMob 簡単に処理できるようになりました。

前提条件

スタートガイドを完了している。

Android API レベル 21 以降（Android の場合）

GDPR 関連の要件に取り組んでいる場合は、IAB の要件が EU 同意メッセージに与える影響

メッセージタイプを作成する

AdMob アカウントの [プライバシーとメッセージ] タブで、使用可能なユーザーメッセージタイプのいずれかを使用してユーザーメッセージを作成します。UMP SDK は、プロジェクトに設定されたアプリケーション ID から作成されたユーザーメッセージを表示しようとします。 AdMob アプリケーションにメッセージが構成されていない場合、SDK はエラーを返します。

詳しくは、プライバシーとメッセージについてをご覧ください。

SDK をインストールする

手順に沿って Google Mobile Ads（GMA）C++ SDK をインストールします。UMP C++ SDK は GMA C++ SDK に含まれています。
続行する前に、プロジェクトでアプリの AdMob アプリ ID を構成していることを確認してください。

コードで ConsentInfo::GetInstance() を呼び出して、UMP SDK を初期化します。

Android では、NDK から提供される JNIEnv と Activity を渡す必要があります。この操作は、GetInstance() を初めて呼び出すときにのみ行います。
または、アプリで Firebase C++ SDK をすでに使用している場合は、初めて GetInstance() を呼び出すときに firebase::App を渡すことができます。

#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() の呼び出しはすべて同じインスタンスを返します。

UMP SDK の使用が終了したら、ConsentInfo インスタンスを削除することで SDK をシャットダウンできます。

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

`Future` を使用して非同期オペレーションをモニタリングする

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

完了コールバックではなく更新ループポーリングを使用して完了を確認する例については、上記をご覧ください。

必要に応じて同意フォームを読み込んで表示する

最新の同意ステータスを取得したら、ConsentInfo クラスでLoadAndShowConsentFormIfRequired() を呼び出して同意フォームを読み込みます。同意ステータスが必須の場合、SDK はフォームを読み込み、指定された FormParentからすぐに表示します。 Future 完了呼び出されます。同意が不要な場合は、すぐに Future 完了呼び出されます。

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

ユーザーが選択したかフォームを閉じた後にアクションを行う必要がある場合は、LoadAndShowConsentFormIfRequired() から返された Future を処理するコードにそのロジックを配置します。

広告をリクエスト

アプリで広告をリクエストする前に、 ConsentInfo::GetInstance()‑>CanRequestAds()を使用してユーザーから同意を得ているかどうかを確認してください。同意を取得する際には、次の 2 つの場所を確認します。

現在のセッションで同意が取得された後。
RequestConsentInfoUpdate()を呼び出した直後。前回のセッションで同意が得られた可能性があります。遅延を考慮すると、コールバックの完了を待たずに、アプリの起動後すぐに広告の読み込みを開始できるようにすることをおすすめします。

同意取得プロセスでエラーが発生した場合でも、広告のリクエストをお試しください。UMP SDK は前のセッションの同意ステータスを使用します。

次の完全なサンプルでは更新ループポーリングを使用していますが、OnCompletion コールバックを使用して非同期処理をモニタリングすることもできます。コード構造に適した手法を使用してください。

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

プライバシー設定

一部の同意フォームでは、ユーザーがいつでも同意内容を変更する必要があります。必要に応じて、次の手順に沿ってプライバシーオプションボタンを実装します。

手順は次のとおりです。

プライバシー設定ページのボタンなど、プライバシーオプションフォームをトリガーできる UI 要素を実装します。
LoadAndShowConsentFormIfRequired() が完了したら、getPrivacyOptionsRequirementStatus() をチェックして、プライバシーオプションフォームを表示できる UI 要素を表示するかどうかを決定します。
ユーザーが UI 要素を操作したら、showPrivacyOptionsForm() を呼び出してフォームを表示して、ユーザーがいつでもプライバシーオプションを更新できるようにします。

テスト

開発中にアプリとの統合をテストする場合は、次の手順に沿ってプログラムでテストデバイスを登録します。アプリをリリースする前に、これらのテストデバイス 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 では、 ConsentRequestParameters.debug_settings.debug_geographyを使用して、デバイスが EEA または英国にあるかのようにアプリの動作をテストできます。デバッグ設定はテストデバイスでのみ機能します。

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();