S2S 激励回传 API

AppLovin 的服务器可以向您指定的外部服务器发送 S2S 激励广告回传。 在应用用户观看完激励广告，获得奖励资格时，服务器就会向您发送这些回传。 这样可以防止恶意用户在未完成激励广告的情况下尝试获得奖励。

简介

用户观看完通过 MAX 聚合提供的激励广告后，AppLovin 的服务器就可以向外部终端发送回传。 您可以指定接收这些请求的终端。 回传采用 HTTP 或 HTTPS GET 请求的形式。 AppLovin 会在广告播放完后立即发送这些回传，但也可能发生几分钟的延迟。 您可以使用展示时间戳宏，弥合展示与回传时间之间的延迟。

如果 5 秒后，您的终端没有做出响应，那么回传请求就会超时。 如果回传请求超时，AppLovin 会重试回传最多两次。

您可以通过在 Edit Ad Unit 页面中设置服务器端回传 URL 的值来配置这些回传。

示例

https://myrewardedserver.com/rewards?idfa={IDFA}&user_id={USER_ID}&event={EVENT_ID}&token={EVENT_TOKEN}

可用宏

您可以将下表中的任意宏加入到回传 URL。 上述示例 URL 中包含 {IDFA}、{USER_ID}、{EVENT_ID} 和 {EVENT_TOKEN} 宏。 当 AppLovin 服务器向您的终端发出回传时，这些宏名称会被准确的值替换。

名称	描述	示例
{AD_UNIT_ID}	MAX Ad Unit ID（16 位十六进制字符）	9ad0816ac071552a
{AD_UNIT_NAME}	广告单元名称（URL 编码）	My%20App%20Banners
{AMOUNT}	您选择奖励用户的货币金额。您可以在每个广告单元的编辑页面中设置此项。	100
{CC}	用户国家/地区代码 (两个字母)	gb
{CURRENCY}	您选择奖励用户的货币类型（URL 编码）。您可以在每个广告单元的编辑页面中设置此项。	coins
{CUSTOM_DATA}	从集成传入的自定义数据 (URL 编码)。AppLovin 建议字符串的长度不要超过 8192 个字符。	my%20custom%20data
{EVENT_ID}	唯一事件 ID（40 位十六进制字符）	8dc948013d71f…b226e08
{EVENT_TOKEN}	sha1( EVENT_ID + Your-Event-Key )	e000949f6d851…a43cf31
{EVENT_TOKEN_ALL}	sha256（按字母顺序排列的全部1宏，已解码的 URL + Your-Event-Key）	eba615583ed59…5f218702a97a
{IDFA}	iOS IDFA 或 Google 广告 ID	860635ea-…3b30b94
{IDFV}	IDFV	4CD1C3C4-…9387E60
{IP}	用户 IP（IPv6 的值已进行 URL 编码）	162.1.1.1、fe80%3A%3A…890a%0A
{NETWORK_NAME}	MAX 广告平台名称	APPLOVIN_BIDDING
{PACKAGE_NAME}	应用包名 (Android) 或 Bundle ID (iOS)。URL 编码。	com.test.app
{PLACEMENT}	开发者定义的 MAX 广告位名称 (URL 编码)	Launch%20Screen
{PLATFORM}	广告平台	android、ios
{TS}	广告加载时间的时间戳 (整数，UNIX 时间秒数)	1546300800
{USER_ID}	开发者定义的用户 ID (URL 编码)；长度不超过 8192 个字符	7634657898

¹提示：如果 EVENT_TOKEN 是您的一个宏，它将从 “按字母顺序排列的所有宏” 字符串中省略

设置广告位名称

下面的代码片段展示了如何向广告单元添加广告位名称。 广告位名称的值会替换回调请求中的 {PLACEMENT} 宏：

ActionScript

横幅

AppLovinMAX.setBannerPlacement(«ad-unit-ID», «placement»);

MREC

AppLovinMAX.setMRecPlacement(«ad-unit-ID», «placement»);

插屏

AppLovinMAX.showInterstitial(«ad-unit-ID», «placement»);

原生广告

nativeAdLoader.setPlacement(«placement»);

激励广告

AppLovinMAX.showRewardedAd(«ad-unit-ID», «placement»);

Blueprint

横幅

MREC

插屏

激励广告

C++

横幅

UAppLovinMAX::CreateBanner(«ad-unit-ID», «position»);
UAppLovinMAX::SetBannerPlacement(«ad-unit-ID», «placement»);

MREC

UAppLovinMAX::CreateMRec(«ad-unit-ID», «position»);
UAppLovinMAX::SetMRecPlacement(«ad-unit-ID», «placement»);

插屏

UAppLovinMAX::ShowInterstitial(«ad-unit-ID», «placement»);

激励广告

UAppLovinMAX::ShowInterstitial(«ad-unit-ID», «placement»);

C#

横幅

MaxSdk.CreateBanner(«ad-unit-ID», «position»);
MaxSdk.SetBannerPlacement(«ad-unit-ID», "«placement»");

MREC

MaxSdk.CreateMRec(«ad-unit-ID», «position»);
MaxSdk.SetMRecPlacement(«ad-unit-ID», "«placement»");

插屏

MaxSdk.ShowInterstitial(«ad-unit-ID», "«placement»");

激励广告

MaxSdk.ShowRewardedAd(«ad-unit-ID», "«placement»");

Dart

横幅

AppLovinMAX.createBanner(«ad-unit-ID», «position»);
AppLovinMAX.setBannerPlacement(«ad-unit-ID», «placement»);

MREC

AppLovinMAX.createMRec(«ad-unit-ID», «position»);
AppLovinMAX.setMRecPlacement(«ad-unit-ID», «placement»);

插屏

AppLovinMAX.showInterstitial(«ad-unit-ID», placement: «placement»);

激励广告

AppLovinMAX.showRewardedAd(«ad-unit-ID», placement: «placement»);

GDScript

横幅

AppLovinMAX.createBanner(«ad-unit-ID», «position»);
AppLovinMAX.set_banner_placement(«ad-unit-ID», «placement»);

MREC

AppLovinMAX.createMRec(«ad-unit-ID», «position»);
AppLovinMAX.set_mrec_placement(«ad-unit-ID», «placement»);

插屏

AppLovinMAX.show_interstitial(«ad-unit-ID», «placement»);

激励广告

AppLovinMAX.show_rewarded_ad(«ad-unit-ID», «placement»);

Java

横幅

adViewAd.setPlacement( "«placement»" );

插屏

interstitial.showAd( "«placement»" );

激励广告

rewardedAd.showAd( "«placement»" );

原生广告

nativeAdLoader.setPlacement( "«placement»" );

原生广告 (Ad Placer)

MaxAdPlacerSettings settings = new MaxAdPlacerSettings( "«ad-unit-ID»" );
settings.setPlacement( "«placement»" );

JavaScript (Cordova)

横幅

AppLovinMAX.createBanner(«ad-unit-ID», «position»);
AppLovinMAX.setBannerPlacement(«ad-unit-ID», «placement»);

MREC

AppLovinMAX.createMRec(«ad-unit-ID», «position»);
AppLovinMAX.setMRecPlacement(«ad-unit-ID», «placement»);

插屏

AppLovinMAX.showInterstitial(«ad-unit-ID», «placement»);

激励广告

AppLovinMAX.showRewardedAd(«ad-unit-ID», «placement»);

JavaScript (React Native)

横幅 (程序化)

AppLovinMAX.createBanner(«ad-unit-ID», «position»);
AppLovinMAX.setBannerPlacement(«ad-unit-ID», «placement»);

横幅 (原生 UI 组件)

import { AdView, AdFormat } from 'react-native-applovin-max';
⋮
<AdView adUnitId={«ad-unit-ID»}
        adFormat={AdFormat.BANNER}
        placement={«placement»} />

MREC (程序化)

import { MRecAd } from 'react-native-applovin-max';
⋮
MRecAd.createAd(«ad-unit-ID», «position»);
MRecAd.setPlacement(«ad-unit-ID», «placement»);

MREC (原生 UI 组件)

import { AdView, AdFormat } from 'react-native-applovin-max';
⋮
<AdView adUnitId={«ad-unit-ID»}
        adFormat={AdFormat.MREC}
        placement={«placement»} />

插屏

import { InterstitialAd } from 'react-native-applovin-max';
⋮
InterstitialAd.showAd(«ad-unit-ID», "«placement»");

激励广告

import { RewardedAd } from 'react-native-applovin-max';
⋮
RewardedAd.showAd(«ad-unit-ID», "«placement»");

原生广告

<NativeAdView
  adUnitId={«ad-unit-ID»}
  placement="«placement»"
  ⋮
/>

Kotlin

横幅

adView.setPlacement( "«placement»" )

插屏

interstitial.showAd( "«placement»" )

激励广告

rewardedAd.showAd( "«placement»" )

原生广告

nativeAdLoader.setPlacement( "«placement»" )

原生广告 (Ad Placer)

val settings = MaxAdPlacerSettings( "«ad-unit-ID»" )
settings.placement = "«placement»"

Lua

横幅

applovin.create_banner(«ad-unit-ID», «position»)
applovin.set_banner_placement(«ad-unit-ID», «placement»)

MREC

applovin.create_mrec(«ad-unit-ID», «position»)
applovin.set_mrec_placement(«ad-unit-ID», «placement»)

插屏

applovin.show_interstitial(«ad-unit-ID», «placement»);

激励广告

applovin.show_rewarded_ad(«ad-unit-ID», «placement»);

Objective-C

横幅

adView.placement = @"«placement»";
[adView loadAd];

插屏

[interstitialAd showAdForPlacement: @"«placement»"];

激励广告

[rewardedAd showAdForPlacement: @"«placement»"];

原生广告

nativeAdLoader.placement = @"«placement»";

原生广告 (Ad Placer)

MAAdPlacerSettings *settings = [MAAdPlacerSettings settingsWithAdUnitIdentifier: @"«ad-unit-ID»"];
settings.placement = @"«placement»";

Swift

横幅

adView.placement = "«placement»"
adView.loadAd()

插屏

interstitial.show(forPlacement: "«placement»")

激励广告

rewardedAd.show(forPlacement: "«placement»")

原生广告

nativeAdLoader.placement = "«placement»"

原生广告 (Ad Placer)

let settings = MAAdPlacerSettings(adUnitIdentifier: "«ad-unit-ID»")
settings.placement = @"«placement»"

设置内部用户 ID

下面的代码片段展示了如何使用您的内部用户 ID 来标记用户。 User ID 字符串的长度上限为 8192 个字符。

ActionScript

AppLovinMAX.setUserId("«user-ID»");

C#

MaxSdk.SetUserId("«user-ID»");

Java

val settings = AppLovinSdk.getInstance( this ).getSettings();
settings.setUserIdentifier( "«user-ID»" );

JavaScript

AppLovinMAX.setUserId("«user-ID»");

Kotlin

val settings = AppLovinSdk.getInstance( this ).settings
settings.userIdentifier = "«user-ID»"

Lua

applovin.set_user_id("«user-ID»")

Objective-C

ALSdkSettings *settings = [ALSdk shared].settings;
settings.userIdentifier = @"«user-ID»";

Swift

let settings = ALSdk.shared().settings
settings.userIdentifier = "«user-ID»"

获取激励广告的金额和币种

要获取奖励金额和币种，请重写奖励回传：

C#

private void OnRewardedAdReceivedRewardEvent(string adUnitId, MaxSdk.Reward reward, MaxSdkBase.AdInfo adInfo)
{
  print("Rewarded user: " + reward.Amount + " " + reward.Label);
}

Java

@Override
public void onUserRewarded(final MaxAd ad, final MaxReward reward)
{
  System.out.println( "Rewarded user: " + reward.getAmount() + " " + reward.getLabel() );
}

Kotlin

override fun onUserRewarded(ad: MaxAd?, reward: MaxReward?)
{
  System.out.println( "Rewarded user: " + reward!!.getAmount() + " " + reward.getLabel() )
}

Objective-C

- (void)didRewardUserForAd:(MAAd *)ad withReward:(MAReward *)reward
{
  NSLog(@"Rewarded user: %d %@", reward.amount, reward.label);
}

Swift

func didRewardUser(for ad: MAAd, with reward: MAReward)
{
  print("Rewarded user: \(reward.amount) \(reward.label)")
}

自定义数据

以下代码片段展示了如何向回调添加自定义字符串数据。 该字符串数据将替换回调中的 {CUSTOM_DATA} 宏。 AppLovin 建议字符串不要超过 8192 个字符。

注意

在加载横幅广告或 MREC 广告之前，必须设置自定义数据。 否则，数据将不会出现在与广告关联的回调中。

横幅和 MREC

C#

MaxSdk.SetBannerCustomData("«ad-unit-ID»", "«custom-data»"); // Banners
MaxSdk.SetMRecCustomData("«ad-unit-ID»", "«custom-data»"); // MRECs

Java

adViewAd.setCustomData( "«custom-data»" );

JavaScript

BannerAd.setCustomData("«ad-unit-ID»", "«custom-data»"); // Banners
MRec.setCustomData("«ad-unit-ID»", "«custom-data»"); // MRECs

Kotlin

adView.setCustomData( "«custom-data»" )

Objective-C

adView.customData = @"«custom-data»";

Swift

adView.customData = "«custom-data»"

插屏

C#

MaxSdk.ShowInterstitial(«adUnitIdentifier», «placement», «custom data»);

Java

MaxInterstitialAd.showAd(«placement», «custom data»);

JavaScript

InterstitialAd.showAd(interAdUnitId, "«placement»", "«custom data»");

Kotlin

MaxInterstitialAd.showAd(«placement», «custom data»)

Objective-C

-[MAInterstitialAd showAdForPlacement:customData:]

Swift

[interstitialAd showAdForPlacement: @"«placement»" customData: @"«custom-data»"];

激励广告

C#

MaxSdk.ShowRewardedAd(«adUnitIdentifier», «placement», «custom data»);

Java

MaxRewardedAd.showAd(«placement», «custom data»);

JavaScript

RewardedAd.showAd(adUnitId, "«placement»", "«custom data»");

Kotlin

MaxRewardedAd.showAd(«placement», «custom data»)

Objective-C

-[MARewardedAd showAdForPlacement:customData:]

Swift

rewardedAd.show(forPlacement: "«placement»" customData: "«custom-data»")

原生广告

Java

nativeAdLoader.setCustomData( "«custom data»" );

JavaScript

<NativeAdView
  adUnitId={«ad-unit-ID»}
  customData="«custom-data»"
  ⋮
/>

Kotlin

nativeAdLoader.setCustomData( "«custom data»" )

Objective-C

nativeAdLoader.customData = @"«custom data»";

Swift

nativeAdLoader.customData = "«custom data»"