أرباح الإعلانات على مستوى مرّات الظهور

عند تسجيل مرّة ظهور، يقدّم 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")
    }
  }

جافا

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
}

جافا

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) للشركاء
Adjust
AppsFlyer
Singular
Tenjin

قد لا يتم تعديل دليل الشريك للإشارة إلى GMA Next-Gen SDK.

توضّح الأمثلة التالية كيفية إرسال بيانات الإيرادات على مستوى مرّة الظهور إلى شركاء AAP باستخدام GMA Next-Gen SDK:

تعديل

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

جافا

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

AppsFlyer

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

جافا

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

Singular

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

جافا

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

Tenjin

بالنسبة إلى "GMA Next-Gen SDK"، يجب إجراء عملية الدمج باستخدام عنصر JSON. يرسل المثال التالي بيانات الإيرادات على مستوى مرّات الظهور إلى Tenjin باستخدام عنصر JSON:

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

جافا

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

أفضل الممارسات المرتبطة بالتنفيذ

  • يجب ضبط المستمع فور إنشاء عنصر الإعلان أو الوصول إليه، وقبل عرض الإعلان بالتأكيد. يضمن ذلك عدم تفويت أي عمليات استدعاء لأحداث مدفوعة.
  • أرسِل معلومات إيرادات الإعلان على مستوى مرّة الظهور إلى خادم الإحصاءات المفضّل لديك فورًا عند استدعاء دالة الاستدعاء للحدث المدفوع. يضمن ذلك عدم إسقاط أي عمليات استدعاء عن طريق الخطأ وتجنُّب التناقضات في البيانات.

AdValue

‫AdValue هي فئة تمثّل القيمة النقدية المكتسبة من إعلان، بما في ذلك رمز عملة القيمة وتصنيف دقة القيمة المرمّز على النحو التالي.

PrecisionType الوصف
UNKNOWN قيمة إعلان غير معروفة يتم عرض هذه الحالة عند تفعيل إشارة قياس ظهور الإعلان للقيمة الدائمة، ولكن لا تتوفّر بيانات كافية.
ESTIMATED هي قيمة إعلان مقدّرة من بيانات مجمّعة.
PUBLISHER_PROVIDED قيمة إعلان يقدّمها الناشر، مثل التكلفة اليدوية لكل ألف ظهور في مجموعة توسّط
PRECISE هي القيمة الدقيقة المدفوعة مقابل عرض هذا الإعلان.

في حال استخدام ميزة "توسّط AdMob"، يحاول AdMob تقديم قيمة ESTIMATED لمصادر الإعلانات المحسّنة. بالنسبة إلى مصادر الإعلانات غير المحسّنة، أو في الحالات التي لا تتوفّر فيها بيانات مجمّعة كافية لتقديم تقدير مفيد، يتم عرض القيمة PUBLISHER_PROVIDED.

اختبار مرّات الظهور من مصادر الإعلانات المستندة إلى عروض الأسعار

بعد تسجيل حدث مرتبط بإيرادات الإعلان على مستوى مرّة الظهور لمصدر إعلان مستند إلى عروض الأسعار من خلال طلب اختباري، ستتلقّى القيم التالية فقط:

  • ‫UNKNOWN: يشير إلى تصنيف دقة القيمة.
  • 0: يشير إلى قيمة الإعلان.
في السابق، ربما ظهرت لك قيمة أخرى لتصنيف دقة القيمة غير UNKNOWN وقيمة إعلان أكبر من 0.

للاطّلاع على تفاصيل حول إرسال طلب عرض إعلان اختباري، يُرجى الاطّلاع على مقالة تفعيل الأجهزة الاختبارية.