曝光層級廣告收益

選取平台： Android 新選取 Android iOS Unity

廣告曝光時，GMA Next-Gen SDK 會提供該次曝光的相關收益資料。您可以運用這項資料，計算使用者的生命週期價值，或將資料往下游轉送至其他相關系統。

本指南說明如何在 Android 應用程式中，導入曝光層級廣告收益的資料擷取功能。

必要條件

每種廣告格式都有 onAdPaid 事件回呼。 在廣告事件的生命週期中，GMA Next-Gen SDK 會監控曝光事件，並依據賺取金額價值叫用處理常式。

以下範例會處理獎勵廣告的付費事件：

Kotlin

ad.adEventCallback =
  object : RewardedAdEventCallback {
    override fun onAdPaid(adValue: AdValue) {
      // Send the impression-level ad revenue information to your
      // preferred analytics server directly within this callback.

      // Extract the impression-level ad revenue data.
      val valueMicros = adValue.valueMicros
      val currencyCode = adValue.currencyCode
      val precisionType = adValue.precisionType

      val loadedAdSourceResponseInfo = ad.getResponseInfo().loadedAdSourceResponseInfo
      val adSourceName = loadedAdSourceResponseInfo?.name
      val adSourceId = loadedAdSourceResponseInfo?.id
      val adSourceInstanceName = loadedAdSourceResponseInfo?.instanceName
      val adSourceInstanceId = loadedAdSourceResponseInfo?.instanceId
      val extras = ad.getResponseInfo().responseExtras
      val mediationGroupName = extras.getString("mediation_group_name")
      val mediationABTestName = extras.getString("mediation_ab_test_name")
      val mediationABTestVariant = extras.getString("mediation_ab_test_variant")
    }
  }

Java

ad.setAdEventCallback(
    new RewardedAdEventCallback() {
      @Override
      public void onAdPaid(@NonNull AdValue value) {
        // Send the impression-level ad revenue information to your preferred
        // analytics server directly within this callback.

        // Extract the impression-level ad revenue data.
        long valueMicros = value.getValueMicros();
        String currencyCode = value.getCurrencyCode();
        PrecisionType precisionType = value.getPrecisionType();

        AdSourceResponseInfo loadedAdSourceResponseInfo =
            ad.getResponseInfo().getLoadedAdSourceResponseInfo();
        String adSourceName = loadedAdSourceResponseInfo.getName();
        String adSourceId = loadedAdSourceResponseInfo.getId();
        String adSourceInstanceName = loadedAdSourceResponseInfo.getInstanceName();
        String adSourceInstanceId = loadedAdSourceResponseInfo.getInstanceId();

        Bundle extras = ad.getResponseInfo().getResponseExtras();
        String mediationGroupName = extras.getString("mediation_group_name");
        String mediationABTestName = extras.getString("mediation_ab_test_name");
        String mediationABTestVariant = extras.getString("mediation_ab_test_variant");
      }
    });

找出自訂事件廣告來源名稱

針對自訂事件廣告來源，AdSourceResponseInfo.name 屬性會傳回廣告來源名稱 Custom event。如果有多個自訂事件，廣告來源名稱將不足以細分這些事件，因此請按照下列步驟操作，找出特定自訂事件：

  1. 取得 AdSourceResponseInfo.name 屬性。
  2. 設定專屬的廣告來源名稱。

以下範例會為自訂事件設定專屬廣告來源名稱：

Kotlin

private fun getUniqueAdSourceName(loadedAdapterResponseInfo: AdSourceResponseInfo): String {
  var adSourceName = loadedAdapterResponseInfo.name
  if (adSourceName == "Custom Event") {
    if (
      loadedAdapterResponseInfo.adapterClassName ==
        "com.google.ads.mediation.sample.customevent.SampleCustomEvent"
    ) {
      adSourceName = "Sample Ad Network (Custom Event)"
    }
  }
  return adSourceName
}

Java

private String getUniqueAdSourceName(@NonNull AdSourceResponseInfo loadedAdapterResponseInfo) {
  String adSourceName = loadedAdapterResponseInfo.getName();
  if (adSourceName.equals("Custom Event")) {
    if (loadedAdapterResponseInfo
        .getAdapterClassName()
        .equals("com.google.ads.mediation.sample.customevent.SampleCustomEvent")) {
      adSourceName = "Sample Ad Network (Custom Event)";
    }
  }
  return adSourceName;
}

請參閱「擷取廣告回應的相關資訊」，進一步瞭解勝出的廣告來源。

整合應用程式歸因合作夥伴 (AAP)

如需完整資訊，瞭解如何將廣告收益資料轉送至數據分析平台，請參閱合作夥伴指南：

合作夥伴 SDK
調整
AppsFlyer
Singular
Tenjin

合作夥伴指南可能尚未更新，因此不會參照 GMA Next-Gen SDK。

以下範例說明如何使用 GMA Next-Gen SDK，將曝光層級收益資料傳送給 AAP 合作夥伴：

調整

Java

rewardedAd.setAdEventCallback(
    new RewardedAdEventCallback() {
      @Override
      public void onAdPaid(@NonNull AdValue value) {
        // Send ad revenue info to Adjust.
        AdjustAdRevenue adRevenue = new AdjustAdRevenue("admob_sdk");
        adRevenue.setRevenue(value.getValueMicros() / 1000000.0, value.getCurrencyCode());
        if (rewardedAd.getResponseInfo().getLoadedAdSourceResponseInfo() != null) {
          adRevenue.setAdRevenueNetwork(
              rewardedAd.getResponseInfo().getLoadedAdSourceResponseInfo().getName());
        }
        Adjust.trackAdRevenue(adRevenue);
      }
    });

Kotlin

rewardedAd.adEventCallback =
  object : RewardedAdEventCallback {
    override fun onAdPaid(value: AdValue) {
      // Send ad revenue info to Adjust.
      val adRevenue = AdjustAdRevenue("admob_sdk")
      adRevenue.setRevenue(value.valueMicros / 1000000.0, value.currencyCode)
      val loadedAdSourceResponseInfo = rewardedAd.getResponseInfo().loadedAdSourceResponseInfo
      loadedAdSourceResponseInfo?.let { adRevenue.setAdRevenueNetwork(it.name) }
      Adjust.trackAdRevenue(adRevenue)
    }
  }

AppsFlyer

Java

rewardedAd.setAdEventCallback(
    new RewardedAdEventCallback() {
      @Override
      public void onAdPaid(@NonNull AdValue value) {
        long valueMicros = value.getValueMicros();
        String currencyCode = value.getCurrencyCode();

        AFAdRevenueData adRevenueData =
            new AFAdRevenueData(
                "AdMob Mediation", // monetizationNetwork
                MediationNetwork.GOOGLE_ADMOB, // mediationNetwork
                currencyCode, // currencyIso4217Code
                (double) valueMicros // revenue
                );

        Map<String, Object> additionalParameters = new HashMap<>();
        additionalParameters.put(COUNTRY, "US");
        additionalParameters.put(AD_UNIT, AD_UNIT_ID);
        additionalParameters.put(AD_TYPE, AdFormat.REWARDED);

        AppsFlyerLib.getInstance().logAdRevenue(adRevenueData, additionalParameters);
      }
    });

Kotlin

rewardedAd.adEventCallback =
  object : RewardedAdEventCallback {
    override fun onAdPaid(value: AdValue) {
      val valueMicros = value.valueMicros
      val currencyCode = value.currencyCode

      val adRevenueData =
        AFAdRevenueData(
          "AdMob Mediation", // monetizationNetwork
          MediationNetwork.GOOGLE_ADMOB, // mediationNetwork
          currencyCode, // currencyIso4217Code
          valueMicros.toDouble(), // revenue
        )

      val additionalParameters: MutableMap<String?, Any?> = HashMap()
      additionalParameters[COUNTRY] = "US"
      additionalParameters[AD_UNIT] = AD_UNIT_ID
      additionalParameters[AD_TYPE] = AdFormat.REWARDED

      appsflyer.logAdRevenue(adRevenueData, additionalParameters)
    }
  }

單數

Java

rewardedAd.setAdEventCallback(
    new RewardedAdEventCallback() {
      @Override
      public void onAdPaid(@NonNull AdValue value) {
        // Convert revenue from micros to standard units.
        double revenue = value.getValueMicros() / 1000000.0;
        String currency = value.getCurrencyCode();

        // Validate ad revenue data before sending.
        if (revenue > 0 && !currency.isEmpty()) {
          SingularAdData adData = new SingularAdData("AdMob", currency, revenue);
          Singular.adRevenue(adData);
        }
      }
    });

Kotlin

rewardedAd.adEventCallback =
  object : RewardedAdEventCallback {
    override fun onAdPaid(value: AdValue) {
      // Convert revenue from micros to standard units.
      val revenue = value.valueMicros / 1000000.0
      val currency = value.currencyCode

      // Validate ad revenue data before sending.
      if (revenue > 0 && currency.isNotEmpty()) {
        val adData = SingularAdData("AdMob", currency, revenue)
        Singular.adRevenue(adData)
      }
    }
  }

Tenjin

如要使用 GMA Next-Gen SDK，必須透過 JSON 物件整合。以下範例會使用 JSON 物件，將曝光層級收益資料傳送至 Tenjin：

Java

rewardedAd.setAdEventCallback(
    new RewardedAdEventCallback() {
      @Override
      public void onAdPaid(@NonNull AdValue value) {
        ResponseInfo responseInfo = rewardedAd.getResponseInfo();

        // Extract the impression-level ad revenue data.
        long valueMicros = value.getValueMicros();
        String currencyCode = value.getCurrencyCode();
        PrecisionType precisionType = value.getPrecisionType();

        JSONObject json = new JSONObject();
        try {
          json.put("ad_unit_id", AD_UNIT_ID);
          json.put("currency_code", currencyCode);
          json.put("response_id", responseInfo.getResponseId());
          json.put("value_micros", valueMicros);
          if (responseInfo.getLoadedAdSourceResponseInfo() != null) {
            json.put(
                "mediation_adapter_class_name",
                responseInfo.getLoadedAdSourceResponseInfo().getAdapterClassName());
          }
          json.put("precision_type", precisionType);

          tenjinInstance.eventAdImpressionAdMob(json);
        } catch (JSONException e) {
          // Handle error.
        }
      }
    });

Kotlin

rewardedAd.adEventCallback =
  object : RewardedAdEventCallback {
    override fun onAdPaid(value: AdValue) {
      val responseInfo = rewardedAd.getResponseInfo()

      // Extract the impression-level ad revenue data.
      val valueMicros = value.valueMicros
      val currencyCode = value.currencyCode
      val precisionType = value.precisionType

      val json = JSONObject()
      try {
        json.put("ad_unit_id", AD_UNIT_ID)
        json.put("currency_code", currencyCode)
        json.put("response_id", responseInfo.responseId)
        json.put("value_micros", valueMicros)
        responseInfo.loadedAdSourceResponseInfo?.let {
          json.put("mediation_adapter_class_name", it.adapterClassName)
        }
        json.put("precision_type", precisionType)

        tenjinInstance.eventAdImpressionAdMob(json)
      } catch (_: JSONException) {
        // Handle error.
      }
    }
  }

導入最佳做法

  • 建立或取得廣告物件後，立即設定事件監聽器，且務必在顯示廣告前完成，以免錯過任何付費事件回呼。
  • 系統一呼叫付費事件回呼，便立即將曝光層級廣告收益資訊傳送至偏好的數據分析伺服器，避免不小心錯過任何回呼或資料不一致的問題。

AdValue

AdValue 類別代表廣告賺取的金額價值，包含貨幣代碼和精確度型別，編碼方式如下。

PrecisionType 說明
UNKNOWN 廣告價值不明。如已啟用生命週期價值 (LTV) 自動參照通知，但資料不足，則系統會傳回此值。
ESTIMATED 根據匯總資料預估的廣告價值。
PUBLISHER_PROVIDED 由發布商提供的廣告價值，例如中介服務群組中的手動千次曝光出價。
PRECISE 為該廣告支付的精確價值。

如果是 AdMob 中介服務，AdMob 會嘗試針對已最佳化的廣告來源提供 ESTIMATED 值。如果廣告來源未最佳化，或匯總資料不足以計算有意義的預估值，系統將傳回 PUBLISHER_PROVIDED 值。

測試出價廣告來源的曝光

送出測試請求，觸發出價廣告來源的曝光層級廣告收益事件之後，您只會收到下列值：

  • UNKNOWN：表示精確度類型。
  • 0：表示廣告價值。

先前，您看到的精確度類型值可能不是 UNKNOWN，且廣告價值大於 0。

請參閱「啟用測試裝置」，進一步瞭解如何傳送測試廣告請求。