הכנסות מפרסום ברמת החשיפה

בחירת פלטפורמה: Android iOS Unity Android (גרסה קודמת)

כשמתרחשת חשיפה, Google Mobile Ads SDK קורא ל-handler של האירוע בתשלום עם נתוני ההכנסה שמשויכים אליו. הטמעת ה-handler הזה מאפשרת להשתמש בנתונים כדי לחשב את ערך חיי המשתמש, או להעביר את הנתונים למערכות רלוונטיות אחרות.

המדריך הזה נועד לעזור לכם להטמיע תיעוד של נתוני ערך חיי המשתמש (LTV) באפליקציה ל-iOS.

דרישות מוקדמות

הטמעה של גורם מטפל באירועים בתשלום

לכל פורמט מודעה יש מאפיין paidEventHandler מסוג GADPaidEventHandler. במהלך מחזור החיים של אירוע מודעה, Google Mobile Ads SDK עוקב אחרי אירועי חשיפה ומפעיל את ה-handler עם ערך שנצבר.

בדוגמה הבאה מטפלים באירועים בתשלום במודעה מתגמלת:

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

בדוגמאות הבאות מוסבר איך לשלוח נתוני הכנסות ברמת החשיפה לשותפי AAP באמצעות Google Mobile Ads SDK:

Adjust

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

יחיד

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

שיטות מומלצות להטמעה

  • צריך להגדיר את ה-handler מיד אחרי שיוצרים את אובייקט המודעה או מקבלים גישה אליו, ובהחלט לפני שמציגים את המודעה. כך לא תפספסו אף קריאה חוזרת (callback) של אירוע בתשלום.
  • שולחים את פרטי האירוע בתשלום לשרת הניתוח המועדף עליכם מיד כשמתבצעת קריאה ל-method‏ paidEventHandler. כך אפשר לוודא שלא תפספסו בטעות קריאות חוזרות (callbacks) ולמנוע פערים בנתונים.

GADAdValue

‫GADAdValue היא מחלקה שמייצגת את הערך הכספי שהרווחתם ממודעה, כולל קוד המטבע של הערך ורמת הדיוק שלו, שמוצפנים באופן הבא.

GADAdValuePrecision תיאור
GADAdValuePrecisionUnknown ערך מודעה לא ידוע. הערך הזה מוחזר כשהפינגבק של ערך חיי המשתמש מופעל, אבל אין מספיק נתונים זמינים.
GADAdValuePrecisionEstimated הערך המשוער של המודעה על סמך נתונים נצברים.
GADAdValuePrecisionPublisherProvided ערך מודעה שסופק על ידי בעל האפליקציה, כמו ערכי עלות ידנית לאלף חשיפות בקבוצה לבחירת רשת (Mediation).
GADAdValuePrecisionPrecise הערך המדויק ששולם על המודעה הזו.

חשיפות לבדיקה ממקורות מודעות לבידינג

אחרי שמתרחש אירוע של הכנסות מפרסום לפי חשיפות (iLAR) במקור מודעות לבידינג דרך בקשת בדיקה, תקבלו רק את הערכים הבאים:

  • ‫GADAdValuePrecisionUnknown: מציין את רמת הדיוק.
  • ‫0: מציין את ערך המודעה.
בעבר, יכול להיות שראיתם שרמת הדיוק היא ערך אחר מ-GADAdValuePrecisionUnknown וערך המודעה גבוה מ-0.

פרטים על שליחת בקשה להצגת מודעת בדיקה זמינים במאמר הפעלת מכשירי בדיקה.