Skip to content
AppLovin

S2S Rewarded Callback API

AppLovin’s servers can make server-to-server rewarded callbacks to an external server that you define. These callbacks notify you that a user of your app completed a rewarded ad and so that user qualifies for a reward. This protects against malicious users who attempt to gain rewards without finishing rewarded ads.

Introduction

AppLovin’s servers can send callbacks to an external endpoint after the user completes a rewarded ad that is served via MAX mediation. You define which endpoint receives these requests. The callbacks are in the form of HTTP or HTTPS GET requests. AppLovin makes these callbacks soon after the ad completion, but they may be delayed by up to a few minutes. You can use an impression timestamp macro to reconcile any delay between the impression and the callback times.

The callback request times-out if five seconds pass without a response from your endpoint. If the callback request times out, AppLovin will retry the callback up to two times.

You can configure these callbacks by setting the value of Server Side Callback URL in the Edit Ad Unit page for any of your rewarded Ad Units.

Example

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

Available Macros

You can incorporate any of the macros in the following table into your callback URL. The example URL above incorporates the {IDFA}, {USER_ID}, {EVENT_ID}, and {EVENT_TOKEN} macros. AppLovin’s servers replace these macro names with accurate values when the servers make the callback to your endpoint.

NameDescriptionExample
{AD_UNIT_ID}MAX Ad Unit ID (16 hex characters)9ad0816ac071552a
{AD_UNIT_NAME}Ad Unit name (URL-encoded)My%20App%20Banners
{AMOUNT}The amount of currency you choose to award the user. You set this in the Ad Unit edit page for each Ad Unit.100
{CC}Two-letter country code of the usergb
{CURRENCY}The type of currency you choose to award the user (URL-encoded). You set this in the Ad Unit edit page for each Ad Unit.coins
{CUSTOM_DATA}Custom data passed in from the integration (URL-encoded). AppLovin recommends that you keep the size of the string under 8192 characters.my%20custom%20data
{EVENT_ID}Unique event ID, 40 hex characters8dc948013d71f…b226e08
{EVENT_TOKEN}sha1( EVENT_ID + Your-Event-Key )e000949f6d851…a43cf31
{EVENT_TOKEN_ALL}sha256( All† macros alphabetically, URL-decoded + Your-Event-Key )
† Note: if EVENT_TOKEN is one of your macros, it is omitted from the “All macros alphabetically” string.		eba615583ed59…5f218702a97a
{IDFA}iOS IDFA or Google Advertising ID860635ea-…3b30b94
{IDFV}IDFV4CD1C3C4-…9387E60
{IP}User’s IP (IPv6 values are URL-encoded)162.1.1.1 , fe80%3A%3A…890a%0A
{NETWORK_NAME}MAX Ad Network NameAPPLOVIN_BIDDING
{PACKAGE_NAME}App Package Name (Android) or Bundle ID (iOS). URL-encoded.com.test.app
{PLACEMENT}Publisher-defined MAX ad placement name (URL-encoded)Launch%20Screen
{PLATFORM}Platformandroid , ios
{TS}Timestamp of impression (integer, seconds since epoch)1546300800
{USER_ID}Publisher-defined user ID (URL-encoded); maximum length is 8192 characters7634657898

Setting an Ad Placement Name

The following code snippets show you how you can add a placement name to an ad unit. The value of the placement name replaces the {PLACEMENT} macro in postback requests:

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

Ad Unit Identifier. Create Banner: Ad Unit Identifier. Banner Position: Bottom Center. Set Banner Placement: Ad Unit Identifier, Placement: YOUR_BANNER_PLACEMENT.
C++
 
UAppLovinMAX::CreateBanner(«ad-unit-ID», «position»);
UAppLovinMAX::SetBannerPlacement(«ad-unit-ID», «placement»);
C#
 
MaxSdk.CreateBanner(«ad-unit-ID», «position»);
MaxSdk.SetBannerPlacement(«ad-unit-ID», "«placement»");
Dart
 
AppLovinMAX.createBanner(«ad-unit-ID», «position»);
AppLovinMAX.setBannerPlacement(«ad-unit-ID», «placement»);
GDScript
 
AppLovinMAX.createBanner(«ad-unit-ID», «position»);
AppLovinMAX.set_banner_placement(«ad-unit-ID», «placement»);
Java
 
adViewAd.setPlacement( "«placement»" );
JavaScript (Cordova)
 
AppLovinMAX.createBanner(«ad-unit-ID», «position»);
AppLovinMAX.setBannerPlacement(«ad-unit-ID», «placement»);
JavaScript (React Native)
 
AppLovinMAX.createBanner(«ad-unit-ID», «position»);
AppLovinMAX.setBannerPlacement(«ad-unit-ID», «placement»);
Kotlin
 
adView.setPlacement( "«placement»" )
Lua
 
applovin.create_banner(«ad-unit-ID», «position»)
applovin.set_banner_placement(«ad-unit-ID», «placement»)
Objective-C
 
adView.placement = @"«placement»";
[adView loadAd];
Swift
 
adView.placement = "«placement»"
adView.loadAd()

Setting an Internal User ID

The following code snippets show how to tag users with your own internal User ID. The maximum size of the User ID string is 8192 characters.

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

Accessing the Amount and Currency for a Rewarded Ad

To access the reward amount and currency, override the reward callback:

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

Custom Data

The following code snippets show you how to add custom String data to postbacks. This String data replaces the {CUSTOM_DATA} macro in these postbacks. AppLovin recommends that your string contain fewer than 8192 characters.

Banners & MRECs
 
MaxSdk.SetBannerCustomData("«ad-unit-ID»", "«custom-data»"); // Banners
MaxSdk.SetMRecCustomData("«ad-unit-ID»", "«custom-data»"); // MRECs
Interstitials
 
MaxSdk.ShowInterstitial(«adUnitIdentifier», «placement», «custom data»);
Rewarded Ads
 
MaxSdk.ShowRewardedAd(«adUnitIdentifier», «placement», «custom data»);
Native Ads
 
nativeAdLoader.setCustomData( "«custom data»" );
Copyright © 2024 AppLovin
Terms | Privacy | Support | EULA | DMCA