Adxmi ios offers order callback protocol en

来自有米广告开发者WIKI
跳转至: 导航搜索

Adxmi iOS OfferWall Server Callback Protocol

Statements

  • This document is only for iOS platform. For Android, please check out here:Adxmi Android Offerwall Server Callback Interface Protocal
  • The uniform encoding of interface: UTF-8
  • Be suited to developers who use their own server to manage currency points.
  • Once Adxmi gets the feedback data from advertisers, we will report back to developers' server immediately.
  • It will need developers to offer an interface to receive data. The method for interface to receive data: GET.


Procedure

  1. Developers will set up the currency points feedback address in Adxmi's developer background control panel, eg: https://www.adxmi.com/apps#/setting
  2. Once Adxmi's server receives an effective data record, it will feedback to developers' server (with GET method) with the feedback url address which is offered by developers. Relevant parameters will be will plus to the url address as below.


Parameters

Parameter Full Name Parameter Name Type Description
Order ID order Character String(16 bytes) Order ID: This value is unique. If developer receives the same order ID, that means the order is already existed.
App ID app Character String(16 bytes) The Application ID
Ad Name ad Advertisement Name(50 bytes) The advertisement name. If the ad type is app, then the ad name is the application's name
Ad Identify adid Advertisement Number(Integer) ID of Advertisement
User ID user Character String ID of user: User can set up his own ID, or set it as reserved callback field.
Device ID device Character String Device ID: MAC address for iOS. If don't have MAC address, then use Advertising Identifier(IDFA). "https://developer.apple.com/library/ios/documentation/AdSupport/Reference/ASIdentifierManager_Ref/ASIdentifierManager.html#//apple_ref/occ/instp/ASIdentifierManager/advertisingIdentifier"
Channel chn Integer Channel number, it will be 0 for iOS
Revenue revenue Float The revenue that developer can earn.
Points points Integer The currency points that users earn
Order Create Time time Integer The time when Adxmi create the order
AdType ad_type string Value is video or offer wall.
Sign sign Character String(36 Bytes) Signature

Notes:

  • All parameters in this protocol will be encoded in UTF-9.
  • $dev_server_secret: The secret key from developers' server, offered by Adxmi. Enter this page "http://www.adxmi.com/apps#/setting" after logging, find the rewarded ads callback method setting-server callback setting, and set up the server address. After successfully setting, a secret key will be assigned to your app.
    , you can inquire the key in the developers back end control panel.
  • Some fields might contain special characters, please use urldecode when receiving request.


Signature Algorithm

Use all parameters in 【Parameters】 list (except "sign") as key, then get the MD5 value with the key.
Supposed the parameters participate in signature are "k1", "k2" and "k3", their value are "v1", "v2" and "v3", then the computing method is:

  • Build the pair form of "key=value" with the parameters. For example, "k1=v1", "k2=v2", "k3=v3".
  • Sort the pair of key and value with ascending lexicographical order and connect them together, like this "k1=v1k2=v2k3=v3".
  • Add dev_server_secret in the end of the connected character string.
  • The signature value is the MD5 value of the above character string.

Notes:

  • Don't include the sign(signature) parameters when calculating the signature
  • The parameters in signature procedure have not been processed by urlencode.
like this: sign = md5("ad={$ad}adid={$adid}app={$app}chn={$chn}device={$device}order={$order}points={$points}price={$price}sig={$sig}time={$time}user={$user}{$dev_server_secret}");

Example:

Original URL:http://api.developer.com/adxmi.php?order=YM121201PWxw0DGr0f&app=2f3ca4oge6894826&ad=%E7%BE%8E%E4%B8%BD%E8%AF%B4&adid=476&user=ef2&chn=0&points=140&price=0.93&time=1354851585&device=98fee7g64057&sig=b68184af
$dev_server_secret:1234567890

After calculate:

sign=ca8ac4661e283eb8fe119ccabbcd2352
Final URL:http://api.developer.com/adxmi.php?order=YM121201PWxw0DGr0f&app=2f3ca4oge6894826&ad=%E7%BE%8E%E4%B8%BD%E8%AF%B4&adid=476&user=ef2&chn=0&points=140&price=0.93&time=1354851585&device=98fee7g64057&sig=b68184af&sign=ca8ac4661e283eb8fe119ccabbcd2352

Implement in PHP:

 <?php
 $url = 'http://api.developer.com/adxmi.php?order=YM121201PWxw0DGr0f&app=2f3ca4oge6894826&ad=%E7%BE%8E%E4%B8%BD%E8%AF%B4&adid=476&user=ef2&chn=0&points=140&price=0.93&time=1354851585&device=98fee7g64057&sig=b68184af';
 $dev_server_secret = '1234567890';
 $url .= '&sign=' . getUrlSignature($url, $dev_server_secret);
 echo $url, "\n"; 
 
 function getUrlSignature($url, $secret){
   $params = array();
   $url_parse = parse_url($url);
   if (isset($url_parse['query'])){
     $query_arr = explode('&', $url_parse['query']);
     if (!empty($query_arr)){
       foreach($query_arr as $p){
         if (strpos($p, '=') !== false){
           list($k, $v) = explode('=', $p);
           $params[$k] = urldecode($v);
         }
       }
     }
   }
   return getSignature($params, $secret);
 }
 
 function getSignature($params, $secret){
   $str = '';
   ksort($params);
   foreach ($params as $k => $v) {
     $str .= "{$k}={$v}";
   }
   $str .= $secret;
   return md5($str);
 }


Implement in Java:

public class AdxmiSign {
 
  public static void main(String[] args) {
    //test
    HashMap<String, String> ps = new HashMap<String, String>();
    ps.put("order", "abcdef0123456789");
    ps.put("app","abcdef0123456789");
    ps.put("ad","DaXiaZhuan");
    ps.put("adid",Integer.toString(1000));
    ps.put("user","abcdefg");
    ps.put("device","ifa");
    ps.put("chn","0");
    ps.put("price",Double.toString(1.0));
    ps.put("points",Integer.toString(100));
    ps.put("time",Long.toString(10000000));
    ps.put("sig","hjd8f33rsjdfas");
    try{
      String sign=getSignature(ps,"xxxxx");
      System.out.println(sign);
    }catch (Throwable e){
      //TODO Handle Throwable
    }
  }
 
  /**
   * Signature Generation Algorithm
   *
   * @param HashMap<String,String> params - The parameters set, all parameters must be converted to character string type
   * @param String dev_server_secret - The secret key that developers set up in adxmi back end control panel 
   * @return Signature
   * @throws IOException
   */
  public static String getSignature(HashMap<String, String> params, String dev_server_secret) throws IOException {
    // Sort parameters in ascending lexicographical order with their names
    Map<String, String> sortedParams = new TreeMap<String, String>(params);
 
    Set<Map.Entry<String, String>> entrys = sortedParams.entrySet();
    // Traverse the sorted dictionary, connect the parameters with the form of "key=value"
    StringBuilder basestring = new StringBuilder();
    for (Map.Entry<String, String> param : entrys) {
      basestring.append(param.getKey()).append("=").append(param.getValue());
    }
    basestring.append(dev_server_secret);
    System.out.println(basestring.toString());
    // Use MD5 to encrypt the character string
    byte[] bytes = null;
    try {
      MessageDigest md5 = MessageDigest.getInstance("MD5");
      bytes = md5.digest(basestring.toString().getBytes("UTF-8"));
    } catch (GeneralSecurityException ex) {
      throw new IOException(ex);
    }
    // Convert the binary result export from MD5 to hexadecimal in lowercase
    StringBuilder sign = new StringBuilder();
    for (int i = 0; i < bytes.length; i++) {
      String hex = Integer.toHexString(bytes[i] & 0xFF);
      if (hex.length() == 1) {
        sign.append("0");
      }
      sign.append(hex);
    }
    return sign.toString();
  }
}


Verification of Signature

Statements:In the early stage of integrating advertisement SDK, developers might find it fail to pass the verification, then this verification interface will be needed to verify.
Of course, you can also contact our customer service directly. Normal verification logic will be implemented by developers themselves.

Supposed that developers receive the feedback request from Adxmi is: http://api.developer.com/adxmi.php?order=YM130402cygr_UTb42&app=30996ced018a2a5e&ad=KC%E7%BD%91%E7%BB%9C%E7%94%B5%E8%AF%9D&user=1141058&device=50ead626ae6e&chn=0&points=7&time=1364890524&sig=15b3dfe0&price=0.749&adid=853&sign=7118194d2da288e6b02878dd9ac07213

If the calculating signature is different with the receiving signature, you can make the below request to test: http://ios.wall.youmi.net/v2/check_fb_sig?order=YM130402cygr_UTb42&app=30996ced018a2a5e&ad=KC%E7%BD%91%E7%BB%9C%E7%94%B5%E8%AF%9D&user=1141058&device=50ead626ae6e&chn=0&points=7&time=1364890524&sig=15b3dfe0&price=0.749&adid=853&sign=7118194d2da288e6b02878dd9ac07213

Just replace http://api.kaifazhe.com/adxmi.php with http://ios.wall.youmi.net/v2/check_fb_sig 
This test link will output the corresponding result.


Return Value

  1. Adxmi will proceed the next operation according to the returning http status code from developers' server. The normal http status code should be 200 or 403.
  2. If the http status code is 200, that means developers already received and processed the message normally.
  3. If the http status code is 403, that means developers refuse this request, which also means middle-tier server will not repeatedly make request to developers' server.
  4. If timeout, or the http status code isn't 200 nor 403, the middle-tier server will make request to developers' server again in the next cycle.
  5. There will be delays in the next cycle request to developers' server, the delay time will respectively be: 5s, 10s, 60s, 300s, 600s, 3600s(since last request). Which means, in the worst case, Adxmi will send seven requests. If all of the seven requests fail, the link will be discarded.
  6. Because of network issues or other reasons, developers' server will receive multiple records with the same order ID. In this case, developers' server need to abandon the duplicate records, and output with http status code 403. That is to say, Developers' server need to remove the duplication of receiving message.