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

اختيار النظام الأساسي: Android iOS Unity Android (قديم)

عند حدوث ظهور، يستدعي "Google Mobile Ads SDK" معالِج الأحداث المدفوعة مع بيانات الإيرادات المرتبطة به. من خلال تنفيذ هذا المعالج، يمكنك استخدام البيانات لاحتساب القيمة الدائمة للمستخدم أو إعادة توجيه البيانات إلى أنظمة أخرى ذات صلة.

يهدف هذا الدليل إلى مساعدتك في تسجيل بيانات القيمة الدائمة في تطبيق iOS.

المتطلبات الأساسية

تنفيذ معالج الأحداث المدفوعة

يحتوي كل شكل إعلان على سمة paidEventHandler من النوع GADPaidEventHandler. أثناء مراحل نشاط حدث الإعلان، يراقب Google Mobile Ads SDK أحداث مرات الظهور ويستدعي المعالج بقيمة مكتسبة.

يتناول المثال التالي الأحداث المدفوعة في "إعلان مقابل مكافأة":

Swift

rewardedAd?.paidEventHandler = { adValue in
  // 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

rewardedAd.paidEventHandler = ^(GADAdValue *_Nonnull 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. إذا كنت تستخدم أحداثًا مخصّصة متعددة، لن يكون اسم مصدر الإعلان مفصّلاً بما يكفي للتمييز بين الأحداث المخصّصة المتعددة. للعثور على حدث مخصّص معيّن، اتّبِع الخطوات التالية:

  1. احصل على السمة adNetworkClassName.
  2. اضبط اسمًا فريدًا لمصدر الإعلان.

يحدّد المثال التالي اسم مصدر إعلان فريدًا لحدث مخصّص:

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

توضّح الأمثلة التالية كيفية إرسال بيانات الإيرادات على مستوى مرّة الظهور إلى شركاء "برنامج شركاء التطبيقات" باستخدام 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);
    }
  };
}

أفضل الممارسات المتعلّقة بالتنفيذ

  • Set the handler immediately once you create or get access to the ad object, and definitely before showing the ad. يضمن ذلك عدم تفويت أي عمليات استدعاء لأحداث مدفوعة.
  • أرسِل معلومات الحدث المدفوع إلى خادم الإحصاءات المفضّل لديك فورًا عند استدعاء طريقة paidEventHandler. يضمن ذلك عدم إسقاط أي عمليات ردّ آلي عن طريق الخطأ وتجنُّب أي تفاوت في البيانات.

GADAdValue

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

GADAdValuePrecision الوصف
GADAdValuePrecisionUnknown قيمة إعلان غير معروفة يتم عرض هذه الحالة عند تفعيل إشارة قياس ظهور الإعلان للقيمة الدائمة، ولكن لا تتوفّر بيانات كافية.
GADAdValuePrecisionEstimated هي قيمة إعلان مقدّرة من بيانات مجمّعة.
GADAdValuePrecisionPublisherProvided قيمة الإعلان المقدّمة من الناشر، مثل التكلفة اليدوية لكل ألف ظهور في مجموعة توسّط
GADAdValuePrecisionPrecise هي القيمة الدقيقة المدفوعة مقابل عرض هذا الإعلان.

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

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

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

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