ToBid

English

简体中文

English

简体中文

激励视频服务端验证
Server-side incentives ​

1.激励视频服务端验证介绍
Introduction to incentive video server verification ​

服务器端验证 (Server-side verification) 是对应用内激励视频广告观看行为进行的额外验证，可规避欺骗客户端回调来奖励用户的行为。 您可以使用服务器端验证对每一次激励视频广告观看行为进行验证，每次用户看完激励视频广告之后，ToBid 都会使用您在设置聚合广告位时提供的回传网址对此次观看行为进行信息回传。开发者可参考服务端验证信息，自行判断进行奖励的下发。
Server-side verification is an additional verification of in-app rewarded video ad viewing behavior, which can avoid deceiving client callbacks to reward users. You can use server-side verification to verify each rewarded video ad viewing behavior. Every time a user finishes watching a rewarded video ad, ToBid will use the callback URL you provided when setting up the aggregated ad slot to send back information about the viewing behavior. Developers can refer to the server-side verification information and make their own judgment on issuing rewards.

激励视频服务端验证功能需要 ToBid SDK 版本>=2.0.0
The rewarded video server verification function requires ToBid SDK version >= 2.0.0

2.ToBid 服务器端验证使用流程
ToBid server-side verification usage process ​

使用服务端激励验证，仅需以下步骤：
To use server-side incentive verification, only the following steps are required:

  • 前往【聚合管理】-【流量管理】-点击应用进入【聚合广告列表】， 点击编辑激励视频聚合广告位
    Go to [Aggregation Management] - [Traffic Management] - click the application to enter the [Aggregation Ad List], click to edit the rewarded video aggregation ad position
  • 打开【服务器回调】开关，填写并保存激励服务端回调相关参数，例如回调地址等。若开发者需要通过回调回传 user_id、自定义用户数据等信息，可参考此文档 SDK 参数传入模块。
    Turn on the [Server Callback] switch, fill in and save the incentive server callback related parameters, such as callback address, etc. If the developer needs to return user_id , custom user data and other information through callback, please refer to this document SDK parameter transfer module.
  • 用户使用 ToBid SDK 2.0.0 及其以上版本观看完成激励视频后，ToBid 服务端将通过平台设置的回调地址通知开发者。开发者可以通过服务端回调中的信息，自行判断是否下发奖励。
    After the user has watched the rewarded video using ToBid SDK 2.0.0 or above, the ToBid server will notify the developer through the callback address set by the platform. The developer can use the information in the server callback to decide whether to issue the reward.

2.1 服务端验证平台字段说明
Server Verification Platform Field Description ​

在编辑激励视频聚合广告位页面，开发者可以编辑如图所示的信息。
On the page for editing rewarded video aggregate ad slots, developers can edit the information as shown in the figure.

回调url处，可填写完整回调url，ToBid将自动解析对应宏参数。您也可单独输入回调地址前半部分，与ToBid相关参数在下方进行手动添加。
In the callback url, you can fill in the complete callback url, and ToBid will automatically parse the corresponding macro parameters. You can also enter the first half of the callback address separately, and manually add the parameters related to ToBid below.

图片名称
  • 回调 URL： ToBid 在用户看完激励广告后，以 GET 方式给开发者通知的地址。例如：
    Callback URL: ToBid After the user has watched the rewarded ad, the developer is notified of the address in GET mode. For example:
http://www.mysite.com/granting.php?appUserId={{USER_ID}}&rewardName={{REWARD_NAME}}&rewardAmount={{REWARD_AMOUNT}}&transId={{TRANS_ID}}&placementId={{PLACEMENT_ID}}&networkId={{NETWORK_ID}}&aggrplacementId={{AGGR_PLACEMENT_ID}}&sign={{SIGN}}&extraInfo={{EXTRAINFO}}&price={{PRICE}}

注意

{} 括号中的值是宏字段，实际的请求中 ToBid 均会替换真实字段；url中需包含所有宏，但值都由开发者自定义，没有值可以传空
warning
The value in the {} brackets is a macro field. In the actual request, ToBid will replace the real field. The url must contain all macros, but the values ​​are customized by the developer. If there is no value, it can be empty.

  • 奖励名称： 聚合广告位设置的奖品名称；例如：金币、积分等。
    Reward name: The name of the prize set for the aggregated ad slot; for example: gold coins, points, etc.
  • 奖励数量： 聚合广告位设置的奖励数量。
    Reward Quantity: The number of rewards set for the aggregated ad slot.
  • Security Key： 密钥。点击"生成"，系统会更新密钥（谨慎点击）。该字段用于生成回调验证签名，以及对价格进行加密，具体可参见服务端验证回传参数说明 中关于签名{{SIGN}}和价格{{PRICE}}的字段说明
    Security Key: key. Click "Generate" and the system will update the key (click carefully). This field is used to generate the callback verification signature and encrypt the price. For details, please refer to the field description of signature and price in the server verification return parameter description

2.2 服务端验证回传参数说明
Server Verification Return Parameter Description ​

ToBid 服务端验证目前支持以下信息，开发者回调地址中需要包含对应的参数宏。
ToBid server-side verification currently supports the following information, and the developer's callback address needs to include the corresponding parameter macro

参数宏
Parameter Macros		参数类型
Parameter Type		说明
illustrate
{{USER_ID}}string开发者应用的用户id，可通过SDK 激励视频的 user_id 字段传入，使用激励视频服务端验证，该字段必传。客户端传入方法 iOS参考 ；安卓参考
The user ID of the developer's application can be passed in through the user_id field of the SDK rewarded video. This field must be passed when using the rewarded video server for verification. Client-side passing method iOS reference ; Android reference
{{TRANS_ID}}string服务端生成的trans_id，具有唯一性，用于标识此次广告观看行为。 开发者可通过此 id 对奖励 发放行为进行去重校验，避免重复发放奖励
The trans_id generated by the server is unique and is used to identify the ad viewing behavior. Developers can use this id to perform deduplication verification on reward issuance to avoid duplicate issuance of rewards.
{{REWARD_AMOUNT}}int奖励数量 ，开发者在编辑激励视频服务端回调信息的页面填写的奖励数量。
The amount of reward is filled in by the developer when editing the page for the callback information of the incentive video server.
{{REWARD_NAME}}string奖励名称 ，开发者在编辑激励视频服务端回调信息的页面填写的奖励名称。
Reward name, which is filled in by the developer when editing the callback information of the incentive video server.
{{PLACEMENT_ID}}stringToBid 聚合广告位id，观看此次激励视频的聚合广告位id
ToBid ad slot id, the aggregated ad slot id for watching this incentive video
{{NETWORK_ID}}string此次激励视频所属的广告平台，广告平台对应的ID参考
The advertising platform to which this rewarded video belongs, the ID corresponding to the advertising platform
{{AGGR_PLACEMENT_ID}}string此次激励视频所属的广告平台的代码位id。注意，此字段仅传输唯一代码位id，对于 Mintegral 渠道，回传 unitId
The code bit id of the advertising platform to which this rewarded video belongs. Note that this field only transmits the unique code bit id. For Mintegral channels, it returns unitId
{{PRICE}}string当次广告播放的 排序价格 。仅 SDK 3.0.0 版本及其以上支持，其他版本替换为空字符。价格字段需要先使用 urldecode后，再使用base64 decode，最后使用 AES256 算法加解密，密钥为对应聚合广告位的Security Key，填充方式：pkcs5。币种：CNY，单位分，具体代码示例可参考 2.5 价格解密示例
The ranking price of the ad played at that time . Only SDK 3.0.0 and above versions support it. Other versions replace it with an empty character. The price field needs to be urldecoded first, then base64 decoded, and finally encrypted and decrypted using the AES256 algorithm. The key is the Security Key of the corresponding aggregated ad slot. The filling method is pkcs5. Currency: CNY, unit cents. For specific code examples, please refer to 2.5 Price Decryption Example
{{SIGN}}string签名校验。为了保证数据的安全性，平台回调参数中包含了签名信息，签名方式是将激励回调设置中的Security Key加上,中间以冒号分隔(伪代码：securityKey +":"+trans_id),对拼接完成后的字符串进行sha256摘要运算。这样可以确保trans_id的真实性。建议开发者同时实现trans_id去重校验能力，以此来提高奖励发放的安全性。
Signature verification. In order to ensure the security of data, the platform callback parameters contain signature information. The signature method is to add the Security Key in the incentive callback setting, separated by a colon (pseudo code: securityKey +":"+trans_id), and perform sha256 digest operation on the concatenated string. This ensures the authenticity of trans_id. It is recommended that developers also implement trans_id deduplication verification capabilities to improve the security of reward issuance.
{{EXTRAINFO}}string通过 SDK的WindMillAdRequest类的options属性传入，options是个字典，key和value都是媒体自定义的，具体代码可参考
It is passed in through the options property of the SDK WindMillAdRequest class. Options is a dictionary, and the key and value are customized by the media. For specific codes, please refer to
{{THIRD_TRANS_ID}}string三方广告激励回调中transid，依赖SDK3.3.0版本。当前支持广告网络：百度联盟、优量汇
Transid in the third-party advertising incentive callback depends on SDK version 3.3.0. Currently supported advertising networks: Baidu Alliance, Youlianghui
{{NETWORK_AD_TYPE}}int三方广告源的原始广告类型。
1代表激励视频
2代表开屏广告
4代表插屏广告
5代表原生广告
7代表Banner广告
依赖SDK3.9.0版本

Original ad types of third-party ad sources.
1 Rewarded video ad
2 Splash ad
4 Interstitial ad
5 Native ad
7 Banner ad
Dependent on SDK version 3.9.0
{{REWARD_TIMING}}int激励发放时机。
0 默认激励发放时机；(三方广告源为激励视频类型时，依赖三方激励回调接口发放奖励)
1 广告关闭时机；（仅支持多类型优选-三方广告源为插屏或开屏时，广告关闭时机发放奖励）
2 广告点击时机；（仅支持多类型优选-三方广告源为插屏或开屏时，广告点击时机发放奖励）
依赖SDK3.9.0版本

Timing for Incentive Distribution:
0： Default Incentive Distribution Timing(When the third-party ad source is of the incentivized video type, rewards are distributed based on the third-party incentive callback interface)
1： Ad Closure Timing(Supported only for multi-type optimization - when the third-party ad source is an interstitial or splash ad, rewards are distributed when the ad is closed)
2： Ad Click Timing(Supported only for multi-type optimization - when the third-party ad source is an interstitial or splash ad, rewards are distributed when the ad is clicked)
Depends on SDK version 3.9.0
{{THIRD_CODE_PRICE}}string三方渠道的加密价格（当前支持百度渠道）
依赖SDK4.0.1及以上版本

The encryption price for the three-party channel (currently supporting the Baidu channel)
Requires SDK version 4.0.1 or above
{{APP_VERSION}}string开发者应用版本号
iOS SDK4.1.0版本支持;Android SDK4.3.0版本支持

App Version
from iOS SDK4.1.0,Android SDK4.3.0
{{SDK_VERSION}}string聚合sdk版本号

SDK Version

2.3 签名校验生成示例
Signature verification generation example ​

sha256工具类（Java版本）
sha256 tool class (Java version)

引入maven
Import Maven

xml
<groupId>commons-codec</groupId>
<artifactId>commons-codec</artifactId>
<version>1.15</version>
<dependency></dependency>
Java
import org.apache.commons.codec.binary.Hex;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
public class Sha256Util {
  /***
   * 利用Apache的工具类实现SHA-256加密
   *
   * @param str 加密的报文
   * @return String
   */
  public static String getSHA256Str(String str) {
    MessageDigest messageDigest;
    String encodeStr = "";
    try {
      messageDigest = MessageDigest.getInstance("SHA-256");
      byte[] hash = messageDigest.digest(str.getBytes(StandardCharsets.UTF_8));
      encodeStr = Hex.encodeHexString(hash);
    } catch (Exception e) {
      e.printStackTrace();
    }
    return encodeStr;
  }
}

使用：
use:

securityKey 取自聚合广告位服务端回调设置中的Security Key参见 服务端验证平台字段说明
securityKey is taken from the Security Key in the callback setting of the aggregated ad slot server. See the field description of the server verification platform.

Java
String signString = securityKey + ":" + trans_id;
Sha256Util.getSHA256Str( signString );

2.4 回调响应
Callback Response ​

如果回调通过了开发者的全部验证，开发者需要返回以下JSON数据：
If the callback passes all verifications of the developer, the developer needs to return the following JSON data:

json
"isValid":true
字段定义
Field Definition		字段值或释义
Field value or interpretation		字段类型
Field Type		备注
Remark
isValidtrue/falseBOOL开发者服务端收到请求后判断回调结果，返回给 ToBid 服务器的校验结果。
After receiving the request, the developer server determines the callback result and returns the verification result to the ToBid server.

如果因为网络原因没有收到回调响应，ToBid 会每隔200毫秒重试3次。If no callback response is received due to network reasons, ToBid will retry 3 times every 200 milliseconds.

2.5 价格解密示例
Price Decryption Example ​

解密过程说明
Decryption process description ​

开发者需要对收到的价格参数进行解密处理：
Developers need to decrypt the received price parameters:

1、首先执行urldecode操作
First perform the urldecode operation

2、使用Base64进行decode操作
Use Base64 for decoding

3、使用AES/ECB/PKCS5Padding算法对字符串进行解密。解密使用的key取自聚合广告位服务端回调设置中的Security Key参见 服务端验证平台字段说明
Use AES/ECB/PKCS5Padding algorithm to decrypt the string. The key used for decryption is taken from the Security Key in the callback setting of the aggregated ad slot server. See the field description of the server verification platform .

Java Example ​

Java
import java.net.URLDecoder;
import java.nio.charset.StandardCharsets;
import java.security.InvalidAlgorithmParameterException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;

import javax.crypto.BadPaddingException;
import javax.crypto.Cipher;
import javax.crypto.IllegalBlockSizeException;
import javax.crypto.NoSuchPaddingException;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;

public class TestAes {
	public static final String ALGORITHM = "AES";
	public static final String SECRET_AES_ECB_MODE = "ECB";
	public static final String SECRET_AES_PKCS5_PADDING = "PKCS5Padding";

	/**
	 * 解密
	 *
	 * <p>
	 * byte[] -> byte[]
	 *
	 * @param mode       模式
	 * @param padding    填充
	 * @param key        密钥
	 * @param iv         向量，如果模式不用向量，可传递null
	 * @param ciphertext 密文
	 * @return 明文
	 */
	public static byte[] decrypt(String mode, String padding, byte[] key, byte[] iv, byte[] ciphertext) {
		return doBytes(mode, padding, key, iv, ciphertext, Cipher.DECRYPT_MODE);
	}

	private static byte[] doBytes(String mode, String padding, byte[] key, byte[] iv, byte[] input, int opMode) {
		Cipher cipher = createCipher(mode, padding, key, iv, opMode);
		try {
			byte[] output = cipher.doFinal(input);
			return output;
		} catch (IllegalBlockSizeException | BadPaddingException e) {
			throw new RuntimeException(e);
		}
	}

	private static Cipher createCipher(String mode, String padding, byte[] key, byte[] iv, int opMode) {
		SecretKeySpec keySpec = new SecretKeySpec(key, ALGORITHM);
		IvParameterSpec ivSpec = null;
		if (iv != null) {
			ivSpec = new IvParameterSpec(iv);
		}

		String transformation = ALGORITHM + "/" + mode + "/" + padding;
		Cipher cipher;
		try {
			cipher = Cipher.getInstance(transformation);
			cipher.init(opMode, keySpec, ivSpec);
			return cipher;
		} catch (NoSuchAlgorithmException | NoSuchPaddingException | InvalidKeyException
				| InvalidAlgorithmParameterException e) {
			throw new RuntimeException(e);
		}
	}

	public static void main(String[] args) {

		// 原始价格，单位为分
		String price = "1000";

		// 聚合广告位 Security Key
		String secretKey = "xm3k88pem11a5cdg7gqn8agoxnh328m9";

		// 平台使用上述key，对price加密、base64 encode、url encode之后得到的加密价格串
		String encryptedPrice = "1CIoSLK1Ye2SAAgNB5kiYQ%3D%3D";

		// 首先对收到的加密字符串进行 URL decode
		String decodedString = URLDecoder.decode(encryptedPrice, StandardCharsets.UTF_8);

		// 再对URL decode 之后的价格进行Base64 decode
		byte[] encryptedBytes = Base64.getDecoder().decode(decodedString.getBytes());

		// 进行解密
		byte[] decryptedBytes = TestAes.decrypt(SECRET_AES_ECB_MODE, SECRET_AES_PKCS5_PADDING, secretKey.getBytes(),
				null, encryptedBytes);

		String decryptedPrice = new String(decryptedBytes);

		// 解密后，价格应该等于1000
		System.out.println(price.equals(decryptedPrice));
	}
}

Python example ​

Python
import base64
import urllib.parse

from Crypto.Cipher import AES
from Crypto.Util.Padding import unpad


BLOCK_SIZE = 16

#价格明文
price = '1000'

#聚合广告位的Security Key
secret_key = b'xm3k88pem11a5cdg7gqn8agoxnh328m9'

#平台使用上述key，对price加密，base64 encode，url encode之后得到的加密价格串
encrypted_price = '1CIoSLK1Ye2SAAgNB5kiYQ%3D%3D'

#开始解密过程
#首先对加密串进行url decode
url_decoded_string = urllib.parse.unquote(encrypted_price)

#再对字符串进行base64 decode
base64_decoded_string = base64.b64decode(url_decoded_string)

#对字符串进行AES解密
f = AES.new(secret_key, mode=AES.MODE_ECB)
raw_res = unpad(f.decrypt(base64_decoded_string), BLOCK_SIZE).decode("utf-8")

print(raw_res)

PHP example ​

PHP
<?php

function pkcs7_pad($text, $blocksize)
{
    $pad = $blocksize - (strlen($text) % $blocksize);
    return $text . str_repeat(chr($pad), $pad);
}

function pkcs7_unpad($text)
{
    $pad = ord($text[strlen($text) - 1]);
    if ($pad > strlen($text)) return false;
    if (strspn($text, chr($pad), strlen($text) - $pad) != $pad) return false;
    return substr($text, 0, -1 * $pad);
}

function decryptData($input,$key){
        $cipher = "aes-256-ecb";
        $output=@openssl_decrypt($input, $cipher , $key);
        if($output===FALSE)
            echo "decrypt data error";
        return $output;
}

if (!in_array('aes-256-ecb',openssl_get_cipher_methods())){
    echo "please install openssl_encrypt\n e.g.:https://www.php.net/manual/zh/book.openssl.php\n";
    die;
}

$secret_key='xm3k88pem11a5cdg7gqn8agoxnh328m9';

//平台加密后的价格
$ency_text='1CIoSLK1Ye2SAAgNB5kiYQ%3D%3D';

//解密后，价格应该等于1000
echo "ori_price : ".decryptData(urldecode($ency_text),$secret_key)."\n";

?>

3.服务器端验证 SDK 相关参数使用说明
Instructions for using the server-side verification SDK related parameters ​

使用激励视频服务端验证时，开发者需要按照要求在平台上做相应的参数配置，并且通过以下方法传入对应的宏信息。 客户端本地提供的 Trans_ID，可用于校验和服务端回调信息的一致性。开发者可根据需求使用。
When using the incentive video server for verification, developers need to configure the corresponding parameters on the platform as required, and pass in the corresponding macro information through the following methods. The Trans_ID provided locally by the client can be used to verify the consistency of the callback information with the server. Developers can use it according to their needs.

3.1 iOS ​

开发者可通过以下方法传入 user_id 以及一些自定义信息
Developers can pass in user_id and some custom information through the following methods

objective-c
WindMillAdRequest *request = [WindMillAdRequest request];
request.userId = @"user_id";
request.placementId = @"ea1f8f7b662";
request.options = @{@"test_key":@"test_value"};//s2s激励时自定义参数，对应{{EXTRAINFO}}
WindMillRewardVideoAd *rewardVideoAd = [[WindMillRewardVideoAd alloc] initWithRequest:request];
rewardVideoAd.delegate = self;
[rewardVideoAd loadAdData];

激励视频服务端验证业务中，ToBid 服务端会向开发者服务端发送一个验证请求，同时客户端会给出 - (void)rewardVideoAd:(WindMillRewardVideoAd *)rewardVideoAd reward:(WindMillRewardInfo *)reward 回调，开发者可根据此回调获取服务端回调的 Trans_ID。
In the incentive video server verification business, the ToBid server will send a verification request to the developer server, and the client will give - (void)rewardVideoAd:(WindMillRewardVideoAd *)rewardVideoAd reward:(WindMillRewardInfo *)rewarda callback. The developer can obtain the Trans_ID of the server callback based on this callback.

注意：在满足激励条件时会触发此回调，与是否选择服务端验证以及服务端验证是否成功无关。Note: This callback is triggered when the incentive conditions are met, regardless of whether server-side verification is selected or not, and whether the server-side verification is successful or not.

3.2 Android ​

开发者可通过以下方法传入 user_id 以及一些自定义信息
Developers can pass in user_id and some custom information through the following methods

java
private WMRewardAd rewardVideoAd;

/**
 * PLACEMENT_ID 必填
 * USER_ID 可选
 * OPTIONS 自定义参数，对应服务端回调的{{EXTRAINFO}}
 */
WMRewardAdRequest request = new WMRewardAdRequest(PLACEMENT_ID, USER_ID, OPTIONS);

激励视频服务端验证业务中，ToBid 服务端会向开发者服务端发送一个验证请求，同时客户端会给onVideoRewarded(AdInfo adInfo, WMRewardInfo rewardInfo) 回调，开发者可根据此回调获取服务端回调的 Trans_ID。
In the incentive video server verification business, the ToBid server will send a verification request to the developer server, and the client will give onVideoRewarded(AdInfo adInfo, WMRewardInfo rewardInfo)a callback. The developer can obtain the Trans_ID of the server callback based on this callback.

4.附录
Appendix ​

ToBid 平台支持的广告网络对应 NetworkID 列表 List of NetworkIDs of advertising networks supported by ToBid platform

广告网络
Ad Network		广告网络Id
Ad Network Id
Mintegral1
Vungle4
Applovin5
Unityads6
ironSource7
Sigmob9
Admob11
Tapjoy12
Toutiao13
FaceBook15
gdt16
Kuaishou19
Klevin20
Baidu21
AdScope27