عند تسجيل مرّة ظهور، يقدّم Google Mobile Ads SDK بيانات إيرادات الإعلانات المرتبطة بمرّة الظهور هذه. يمكنك استخدام البيانات لاحتساب القيمة الدائمة للمستخدم أو إعادة توجيه البيانات إلى أنظمة أخرى ذات صلة.
يهدف هذا الدليل إلى مساعدتك في تنفيذ عملية تسجيل بيانات القيمة الدائمة في تطبيق iOS.
المتطلبات الأساسية
- تأكَّد من تفعيل ميزة "إيرادات الإعلان على مستوى مرة الظهور" في واجهة مستخدم AdMob.
- استورِد الإصدار 9.10.0 من Google Mobile Ads SDK أو إصدارًا أحدث.
- إعداد Google Mobile Ads SDK
قبل أن تتمكّن من تلقّي أي إيرادات إعلان على مستوى مرّة الظهور، عليك تنفيذ شكل إعلان واحد على الأقل:
التعامل مع الأحداث المدفوعة
يتضمّن بروتوكول التفويض لكل شكل إعلان طريقة didRecordPaidEventWithAdValue:. أثناء دورة حياة الإعلان، يراقب Google Mobile Ads SDK أحداث مرات الظهور ويستدعي طريقة التفويض هذه باستخدام كائن GADAdValue مكتسب.
يتعامل المثال التالي مع الأحداث المدفوعة لـ "إعلان مقابل مكافأة":
Swift
func ad(_ ad: FullScreenPresentingAd, didRecordPaidEventWith adValue: AdValue) {
// TODO: Send the impression-level ad revenue information to your preferred
// analytics server directly within this callback.
// Extract the impression-level ad revenue data.
let value = adValue.value
let currencyCode = adValue.currencyCode
let precision = adValue.precision
print(
"Ad paid event. Value: \(value) \(currencyCode), with precision: \(precision)."
)
}
Objective-C
- (void)ad:(id<GADFullScreenPresentingAd>)ad didRecordPaidEventWithAdValue:(GADAdValue *)adValue {
// TODO: Send the impression-level ad revenue information to your preferred
// analytics server directly within this callback.
// Extract the impression-level ad revenue data.
NSDecimalNumber *value = adValue.value;
NSString *currencyCode = adValue.currencyCode;
GADAdValuePrecision precision = adValue.precision;
NSLog(@"Ad paid event. Value: %@ %@, with precision: %ld.", value, currencyCode, (long)precision);
}
تحديد اسم مصدر إعلان لحدث مخصّص
بالنسبة إلى مصادر الإعلانات للأحداث المخصّصة، تمنحك السمة adSourceName اسم مصدر الإعلان Custom event. إذا كنت تستخدم أحداثًا مخصّصة متعددة، لن يكون اسم مصدر الإعلان دقيقًا بما يكفي للتمييز بين الأحداث المخصّصة المتعددة. للعثور على حدث مخصّص معيّن، اتّبِع الخطوات التالية:
- احصل على السمة
adNetworkClassName. - اضبط اسمًا فريدًا لمصدر الإعلان.
يحدّد المثال التالي اسم مصدر إعلان فريدًا لحدث مخصّص:
Swift
func uniqueAdSourceName(for loadedAdNetworkResponseInfo: AdNetworkResponseInfo) -> String {
var adSourceName: String = loadedAdNetworkResponseInfo.adSourceName ?? ""
if adSourceName == "Custom Event" {
if loadedAdNetworkResponseInfo.adNetworkClassName
== "MediationExample.SampleCustomEventSwift"
{
adSourceName = "Sample Ad Network (Custom Event)"
}
}
return adSourceName
}Objective-C
- (NSString *)uniqueAdSourceNameForAdNetworkResponseInfo:
(GADAdNetworkResponseInfo *)loadedAdNetworkResponseInfo {
NSString *adSourceName = loadedAdNetworkResponseInfo.adSourceName;
if ([adSourceName isEqualToString:@"Custom Event"]) {
if ([loadedAdNetworkResponseInfo.adNetworkClassName isEqualToString:@"SampleCustomEvent"]) {
adSourceName = @"Sample Ad Network (Custom Event)";
}
}
return adSourceName;
}لمزيد من المعلومات عن مصدر الإعلان الفائز، اطّلِع على مقالة استرداد معلومات عن استجابة الإعلان.
الدمج مع شركاء قياس أداء التطبيقات (AAP)
للحصول على تفاصيل كاملة حول إعادة توجيه بيانات إيرادات الإعلانات إلى منصات الإحصاءات، يُرجى الرجوع إلى دليل الشريك:
| حزمة تطوير البرامج (SDK) للشركاء |
|---|
| Adjust |
| AppsFlyer |
| Singular |
| Tenjin |
توضّح الأمثلة التالية كيفية إرسال بيانات الإيرادات على مستوى مرّة الظهور إلى شركاء AAP باستخدام Google Mobile Ads SDK:
تعديل
Swift
func setPaidEventHandler(rewardAd: RewardedAd) {
rewardAd.paidEventHandler = { adValue in
guard let adRevenue = ADJAdRevenue(source: "admob_sdk") else { return }
adRevenue.setRevenue(adValue.value.doubleValue, currency: adValue.currencyCode)
if let adSourceName = rewardAd.responseInfo.loadedAdNetworkResponseInfo?.adSourceName {
adRevenue.setAdRevenueNetwork(adSourceName)
}
Adjust.trackAdRevenue(adRevenue)
}
}Objective-C
- (void)setPaidEventHandler:(GADRewardedAd *)rewardAd {
NSString *adSourceName = rewardAd.responseInfo.loadedAdNetworkResponseInfo.adSourceName;
rewardAd.paidEventHandler = ^(GADAdValue *_Nonnull adValue) {
ADJAdRevenue *adRevenue = [[ADJAdRevenue alloc] initWithSource:@"admob_sdk"];
if (!adRevenue) {
return;
}
[adRevenue setRevenue:adValue.value.doubleValue currency:adValue.currencyCode];
if (adSourceName) {
[adRevenue setAdRevenueNetwork:adSourceName];
}
[Adjust trackAdRevenue:adRevenue];
};
}AppsFlyer
Swift
func setPaidEventHandler(rewardedAd: RewardedAd) {
rewardedAd.paidEventHandler = { adValue in
let adRevenueData = AFAdRevenueData(
monetizationNetwork: "AdMob Mediation", mediationNetwork: MediationNetworkType.googleAdMob,
currencyIso4217Code: adValue.currencyCode, eventRevenue: adValue.value)
var additionalParameters = [:]
additionalParameters[kAppsFlyerAdRevenueCountry] = "US"
additionalParameters[kAppsFlyerAdRevenueAdUnit] = rewardedAd.adUnitID
additionalParameters[kAppsFlyerAdRevenueAdType] = "Rewarded"
AppsFlyerLib.shared().logAdRevenue(adRevenueData, additionalParameters: additionalParameters)
}
}Objective-C
- (void)setPaidEventHandler:(GADRewardedAd *)rewardedAd {
NSString *adUnitID = rewardedAd.adUnitID;
rewardedAd.paidEventHandler = ^(GADAdValue *_Nonnull adValue) {
AFAdRevenueData *adRevenueData = [[AFAdRevenueData alloc]
initWithMonetizationNetwork:@"AdMob Mediation"
mediationNetwork:AppsFlyerAdRevenueMediationNetworkTypeGoogleAdMob
currencyIso4217Code:adValue.currencyCode
eventRevenue:adValue.value];
NSMutableDictionary *additionalParameters = [[NSMutableDictionary alloc] init];
additionalParameters[kAppsFlyerAdRevenueCountry] = @"US";
additionalParameters[kAppsFlyerAdRevenueAdUnit] = adUnitID;
additionalParameters[kAppsFlyerAdRevenueAdType] = @"Rewarded";
[[AppsFlyerLib shared] logAdRevenue:adRevenueData additionalParameters:additionalParameters];
};
}Singular
Swift
func setPaidEventHandler(rewardedAd: RewardedAd) {
rewardedAd.paidEventHandler = { adValue in
// Extract revenue and currency from AdValue.
let revenue = adValue.value.doubleValue
let currency = adValue.currencyCode
// Validate revenue and currency before sending.
guard revenue > 0, !currency.isEmpty else {
print(
"Invalid ad revenue data: revenue = \(revenue), currency = \(String(describing: currency))"
)
return
}
// Create ad revenue data object.
let data = SingularAdData(
adPlatform: "AdMob",
withCurrency: currency,
withRevenue: NSNumber(value: revenue)
)
// Send to Singular.
Singular.adRevenue(data)
print("Ad revenue sent: \(revenue) \(currency)")
}
}Objective-C
- (void)setPaidEventHandler:(GADRewardedAd *)rewardedAd {
rewardedAd.paidEventHandler = ^(GADAdValue *_Nonnull adValue) {
// Extract revenue and currency from AdValue.
double revenue = adValue.value.doubleValue;
NSString *currency = adValue.currencyCode;
// Validate revenue and currency before sending.
if (revenue <= 0 || currency.length == 0) {
NSLog(@"Invalid ad revenue data: revenue = %f, currency = %@", revenue, currency);
return;
}
// Create ad revenue data object.
SingularAdData *data =
[[SingularAdData alloc] initWithAdPlatform:@"AdMob"
withCurrency:currency
withRevenue:[NSNumber numberWithDouble:revenue]];
// Send to Singular.
[Singular adRevenue:data];
NSLog(@"Ad revenue sent: %f %@", revenue, currency);
};
}Tenjin
Swift
func setPaidEventHandler(rewardedAd: RewardedAd) {
rewardedAd.paidEventHandler = { adValue in
var jsonDict = [:]
jsonDict["ad_unit_id"] = rewardedAd.adUnitID
jsonDict["value_micros"] = adValue.value
jsonDict["currency_code"] = adValue.currencyCode
let responseInfo = rewardedAd.responseInfo
if let responseIdentifier = responseInfo.responseIdentifier {
jsonDict["response_id"] = responseIdentifier
}
if let adNetworkClassName = responseInfo.loadedAdNetworkResponseInfo?.adNetworkClassName {
jsonDict["mediation_adapter_class_name"] = adNetworkClassName
}
do {
let jsonData = try JSONSerialization.data(withJSONObject: jsonDict, options: [])
let jsonString = String(data: jsonData, encoding: .utf8)
TenjinSDK.adMobImpression(fromJSON: jsonString)
} catch {
print("Failed to log AdMob impression: \(error)")
}
}
}Objective-C
- (void)setPaidEventHandler:(GADRewardedAd *)rewardedAd {
NSString *adUnitID = rewardedAd.adUnitID;
GADResponseInfo *responseInfo = rewardedAd.responseInfo;
rewardedAd.paidEventHandler = ^(GADAdValue *_Nonnull adValue) {
NSMutableDictionary *jsonDict = [[NSMutableDictionary alloc] init];
jsonDict[@"ad_unit_id"] = adUnitID;
jsonDict[@"value_micros"] = adValue.value;
jsonDict[@"currency_code"] = adValue.currencyCode;
NSString *responseIdentifier = responseInfo.responseIdentifier;
if (responseIdentifier) {
jsonDict[@"response_id"] = responseIdentifier;
}
NSString *adNetworkClassName = responseInfo.loadedAdNetworkResponseInfo.adNetworkClassName;
if (adNetworkClassName) {
jsonDict[@"mediation_adapter_class_name"] = adNetworkClassName;
}
NSError *error = nil;
NSData *jsonData = [NSJSONSerialization dataWithJSONObject:jsonDict options:0 error:&error];
if (jsonData) {
NSString *jsonString = [[NSString alloc] initWithData:jsonData encoding:NSUTF8StringEncoding];
[TenjinSDK adMobImpressionFromJSON:jsonString];
} else {
NSLog(@"Failed to log AdMob impression: %@", error);
}
};
}أفضل الممارسات المتعلّقة بالتنفيذ
- يجب ضبط المفوَّض فور إنشاء عنصر الإعلان أو الحصول على إذن الوصول إليه، وبالتأكيد قبل عرض الإعلان. يضمن ذلك عدم تفويت أي عمليات استدعاء لأحداث مدفوعة.
- أرسِل معلومات الحدث المدفوع إلى خادم الإحصاءات المفضّل لديك
فورًا عند استدعاء طريقة المفوَّض
didRecordPaidEventWithAdValue:. يضمن ذلك عدم إسقاط أي عمليات استدعاء عن طريق الخطأ وتجنُّب الاختلافات في البيانات.
GADAdValue
GADAdValue هي فئة تمثّل القيمة المالية المكتسَبة من إعلان،
بما في ذلك رمز عملة القيمة وتصنيف دقة القيمة المرمَّز على النحو التالي.
| GADAdValuePrecision | الوصف |
|---|---|
GADAdValuePrecisionUnknown
|
قيمة إعلان غير معروفة يتم عرض هذه الحالة عند تفعيل إشارة قياس ظهور الإعلان للقيمة الدائمة، ولكن لا تتوفّر بيانات كافية. |
GADAdValuePrecisionEstimated
|
هي قيمة إعلان مقدّرة من بيانات مجمّعة. |
GADAdValuePrecisionPublisherProvided
|
قيمة إعلان يقدّمها الناشر، مثل التكلفة اليدوية لكل ألف ظهور في مجموعة توسّط |
GADAdValuePrecisionPrecise
|
هي القيمة الدقيقة المدفوعة مقابل عرض هذا الإعلان. |
اختبار مرّات الظهور من مصادر الإعلانات المستندة إلى عروض الأسعار
بعد تسجيل حدث مرتبط بإيرادات الإعلان على مستوى مرّة الظهور لمصدر إعلان مستند إلى عروض الأسعار من خلال طلب اختباري، ستتلقّى القيم التالية فقط:
-
GADAdValuePrecisionUnknown: يشير إلى تصنيف دقة القيمة.
0: يشير إلى قيمة الإعلان.
GADAdValuePrecisionUnknown وقيمة إعلان أكبر من 0.
للاطّلاع على تفاصيل حول إرسال طلب عرض إعلان اختباري، يُرجى الاطّلاع على مقالة تفعيل الأجهزة الاختبارية.