عند تسجيل مرّة ظهور، يقدّم GMA Next-Gen SDK بيانات إيرادات الإعلانات المرتبطة بمرّة الظهور هذه. يمكنك استخدام البيانات لاحتساب القيمة الدائمة للمستخدم أو إعادة توجيه البيانات إلى أنظمة أخرى ذات صلة.
يهدف هذا الدليل إلى مساعدتك في تسجيل بيانات إيرادات الإعلان على مستوى مرّة الظهور في تطبيق Android.
المتطلبات الأساسية
- تأكَّد من تفعيل ميزة "إيرادات الإعلان على مستوى مرة الظهور" في واجهة مستخدم AdMob.
- إعداد GMA Next-Gen SDK
قبل أن تتمكّن من تلقّي أي إيرادات إعلان على مستوى مرّة الظهور، عليك تنفيذ شكل إعلان واحد على الأقل:
معالِج الأحداث المدفوعة
يتضمّن كل شكل إعلان دالة رد اتصال لحدث
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. إذا كنت تستخدم أحداثًا مخصّصة متعددة، لن يكون اسم مصدر الإعلان دقيقًا بما يكفي للتمييز بين الأحداث المخصّصة المتعددة. للعثور على حدث مخصّص معيّن، اتّبِع الخطوات التالية:
- الحصول على السمة
AdSourceResponseInfo.name - اضبط اسمًا فريدًا لمصدر الإعلان.
يحدّد المثال التالي اسم مصدر إعلان فريدًا لحدث مخصّص:
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.
للاطّلاع على تفاصيل حول إرسال طلب عرض إعلان اختباري، يُرجى الاطّلاع على مقالة تفعيل الأجهزة الاختبارية.