新增广告文档

9e12f814 · 刘添 · fc7bc6a2 · 9e12f814
--- a/Android游戏广告媒体对接说明文档.md
+++ b/Android游戏广告媒体对接说明文档.md
+# 掌游android集成广告SDK
+# 掌游android集成广告SDK
+
+一：SDK概述
+
+1、主要功能
+
+SDK登录
+
+SDK支付
+
+SDK角色上报
+
+SDK激励广告
+
+1.1、接入准备
+
+备注：具体对接方法请根据游戏类型信息接入即可，如不清楚请联系我方技术
+
+1.1、SDK清单文件注册（AndroidManifest.xml）
+
+正式接入前请务必阅读掌玩SDK接入流程的介绍，并且在掌玩SDK平台获取game\_id与game\_secret，此参数将由掌玩游戏对接技术或产品对接，对接时由平台方提供app\_id、app\_status、app\_name、game\_id、PackName、游戏appName等字段信息，请严格阅读对接时平台对接人员提供参数文档
+
+| 名称 | 说明 |
+| --- | --- |
+| game\_id | 游戏在平台的唯一标识。 |
+| game\_secret | 平台方提供，游戏签名秘钥。 |
+| app\_status | 用户在平台登录的投放媒体标识。 |
+| app\_name | 游戏在三方平台标识（快手）。 |
+| pack\_name | 游戏在用户设备安装唯一标识 |
+
+在注册清单中（AndroidManifest.xml）填写对应字段值
+
+```
+<!--掌玩SDK游戏ID-->
+    <meta-data
+        android:name="game_id"
+        android:value="149" />
+
+    <!-- 巨量、快手、腾讯开放平台申请应用，用于转端包选择0 -->
+    <meta-data
+        android:name="app_id"
+        android:value="517181" />
+
+    <!--腾讯广告必填-->
+    <meta-data
+        android:name="secret"
+        android:value="test" />
+
+    <!--快手平台申请应用名称,不是快手投放包可以选择不填写-->
+    <meta-data
+        android:name="app_name"
+        android:value="tlcq" />
+
+    <!--0默认SDK,1表示巨量AD，2表示快手,3表示腾讯-->
+    <meta-data
+        android:name="app_status"
+        android:value="1" />
+
+```
+
+二：快速集成
+
+2.1、引入maven仓库代码
+
+在主工程项目中build.gradle中添加maven
+
+```
+ //掌玩SDK
+        maven { url 'http://nexus.zwwlkj01.top/repository/android-game/' }
+
+        //巨量SDK
+        maven {
+            url 'https://artifact.bytedance.com/repository/Volcengine/'
+        }
+
+        maven { url 'http://nexus.zwwlkj01.top/repository/toutiaoSdk/' }
+
+
+        /*广告媒体*/
+        maven {
+            url 'http://nexus.zwwlkj01.top/repository/AdGameSdk/'
+            allowInsecureProtocol=true
+            credentials {
+                username ""
+                password ""
+            }
+
+        }
+        //Anythink(Core)
+        maven {
+            url "https://jfrog.takuad.com/artifactory/china_sdk"
+        }
+
+        //Csj
+        maven {
+            url "https://artifact.bytedance.com/repository/pangle"
+        }
+
+        maven { url "https://s01.oss.sonatype.org/content/groups/public" }
+
+```
+
+2.2在项目APP目录下的build.gradle中添加SDK版本地址
+
+```
+  implementation 'com.zw.game.advertisement:gameSDk:1.1.0'
+
+  implementation 'androidx.multidex:multidex:2.0.1' //分包，具体根据项目使用添加
+```
+
+SDK为androidx项目，如没有升级到androidx，则建议升级，并在gradle.properties中添加以下代码
+
+```
+android.useAndroidX=true
+kotlin.code.style=official
+android.nonTransitiveRClass=true
+android.enableJetifier=true
+
+```
+
+在注册清单中添加广告的provider
+
+```
+<uses-library android:name="org.apache.http.legacy" android:required="false"/>
+        <provider
+            android:name="androidx.core.content.FileProvider"
+            android:authorities="${applicationId}.fileprovider"
+            android:exported="false"
+            android:grantUriPermissions="true">
+            <meta-data
+                android:name="android.support.FILE_PROVIDER_PATHS"
+                android:resource="@xml/anythink_bk_gdt_file_path" />
+        </provider>
+
+        <provider
+            android:name="com.bytedance.sdk.openadsdk.TTFileProvider"
+            android:authorities="${applicationId}.TTFileProvider"
+            android:exported="false"
+            android:grantUriPermissions="true"
+            tools:replace="android:authorities">
+            <meta-data
+                android:name="android.support.FILE_PROVIDER_PATHS"
+                android:resource="@xml/anythink_bk_tt_file_path" />
+        </provider>
+        <provider
+            android:name="com.qq.e.comm.GDTFileProvider"
+            android:authorities="${applicationId}.gdt.fileprovider"
+            android:exported="false"
+            android:grantUriPermissions="true">
+            <meta-data
+                android:name="android.support.FILE_PROVIDER_PATHS"
+                android:resource="@xml/anythink_bk_gdt_file_path" />
+        </provider>
+
+```
+
+在你的res目录下xml文件夹下新建anythink\_bk\_tt\_file\_path与anythink\_bk\_gdt\_file\_path
+
+anythink\_bk\_gdt\_file\_path
+
+```
+
+
+
+<?xml version="1.0" encoding="utf-8"?>
+
+
+<paths>
+    <external-cache-path
+        name="gdt_sdk_download_path1"
+        path="com_qq_e_download" />
+    <cache-path
+        name="gdt_sdk_download_path2"
+        path="com_qq_e_download" />
+</paths>
+
+```
+
+anythink\_bk\_gdt\_file\_path
+
+```
+<?xml version="1.0" encoding="utf-8"?>
+
+
+<paths>
+    <external-cache-path
+        name="gdt_sdk_download_path1"
+        path="com_qq_e_download" />
+    <cache-path
+        name="gdt_sdk_download_path2"
+        path="com_qq_e_download" />
+</paths>
+```
+
+2.3初始化SDK
+
+在你的工程中application中添加以下代码，没有application则新增application类，并在注册清单中添加你的application
+
+```
+
+public class App extends Application {
+    @Override
+    public void onCreate() {
+        super.onCreate();
+        MultiDex.install(this); // 关键：加载所有 Dex 文件
+        GameAdService.getInstance().initApplication(this);
+    }
+}
+
+
+```
+
+在注册清单添加APP类
+
+```
+    <application
+        android:allowBackup="true"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:name=".App"
+        android:networkSecurityConfig="@xml/network_security_config"
+        android:hardwareAccelerated="true"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.ZyouSdk">
+```
+
+在你的Activity中初始化SDK
+
+```
+GameAdService.getInstance().onCreate(mActivity, new InitZyCallback() {
+            @Override
+            public void onSuccess(int status) {
+                switch (status){
+                    case -1:
+                        showToast("退出登录失败");
+                        break;
+                    case 1:
+                        showToast("初始化成功");
+                        break;
+                    case 2:
+                        showToast("初始化失败");
+                        break;
+                    case 3:
+                        showToast("退出登录成功");
+                        break;
+                    case 4:
+                        showToast("切换登录成功");
+                        break;
+                    default:
+                        showToast("初始化失败");
+                        break;
+                }
+//                status=3 退出登录成功
+                Log.e(TAG,"SDK初始化："+status);
+            }
+
+            @Override
+            public void onFailed(Object o) {
+
+            }
+        });
+
+       ConfigInfo.allowPORTRAIT = false;//默认横屏
+
+```
+
+状态码说明
+
+| 名称 | 说明 |
+| --- | --- |
+| \-1 | 表示玩家退出登录失败 |
+| 1 | SDK初始化完成 |
+| 2 | SDK初始化失败 |
+| 3 | 悬浮球退出登录成功（CP则需要重置游戏状态） |
+| 4 | 悬浮球个人中心切换账号完成（CP需要重置游戏） |
+|  |  |
+
+2.4、SDK登录
+
+```
+ GameAdService.getInstance().showLogin(this,new OnLoginListener() {
+            @Override
+            public void loginSuccess(Object data) {
+
+            }
+            @Override
+            public void loginError(Object data) {
+
+            }
+        });
+
+```
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| status\_code | int | 状态码 |
+| data | object | 返回数据 |
+| msg | string | 描述信息 |
+| data | object | 用户数据 |
+| player\_id | String | 玩家ID |
+| avatar | String | 用户头像 |
+| has\_identify | Boolean | 是否实名 |
+| user\_token | String | 签名token |
+
+2.5 SDK中显示悬浮球
+
+必须在登录完成后调用，可以在登录回调中完成处理
+
+```
+ GameService.getInstance().showBall(activity);//activity为当前Activity上下问题，必须为Activity
+```
+
+2.6、SDK下单
+
+拉起支付面板
+
+```
+public void showPay(String payParam, OnPaymentListener paymentListener)
+```
+
+示例JSON：
+
+```json
+{
+    "order": {
+        "amount": "100",
+        "cp_order_id": "1763379741775",
+        "ext": "测试数据",
+        "product_cnt": "1",
+        "product_desc": "商品",
+        "product_id": "101",
+        "product_name": "1元档充值",
+        "product_price": "100"
+    },
+    "role": {
+        "cp_role_id": "59373816",
+        "event": "other",
+        "role_level": "83",
+        "role_name": "主宰传奇",
+        "role_vip": "0",
+        "server_id": "15139474",
+        "server_name": "主宰服"
+    }
+}
+```
+
+| 名称 | 类型 | 是否必须 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| cp\_order\_id | String | true |  | CP订单ID |
+| amount | number | true |  | 商品总价（单位：分 |
+| product\_price | number | true |  | 商品价格(整数，后台自动换算分) |
+| product\_id | String | true | 0 | 商品ID |
+| product\_cnt | number | true | "0" | 商品数量 |
+| product\_name | string | true | "" | 商品名称 |
+| product\_desc | string | false | "" | 商品描述 |
+| ext | string | true | "" | 订 调用方定义 单额外信息用（json） |
+| event | stringstring | true |  | 事件 |
+| server\_id | string | true |  | 区服id |
+| server\_name | string | true |  | 区服名称 |
+| cp\_role\_id | string | true |  | cp角色id |
+| role\_name | string | true |  | 角色名称 |
+| role\_level | string | true |  | 角色等级 |
+| role\_vip | string | true |  | 角色vip等级 |
+| role\_id | string | true |  | 角色ID |
+
+下单回调通知  （需要游戏服务端完成该接口，接收平台充值成功的信息。）
+
+接口地址：参考服务端文档
+
+2.7、角色上报
+
+参数示例：
+
+```json
+{
+    "cp_account": "w55231582254",
+    "role": {
+        "attack": "0",
+        "chapter_index": "12",
+        "combat_num": "25564",
+        "cp_role_id": "69842111",
+        "event": "create",
+        "gang_name": "大竹帮",
+        "main_city_level": "大司马",
+        "online_time": "15426",
+        "power": "阔克萨斯",
+        "profession": "法师",
+        "reiki_num": "12",
+        "role_level": "15",
+        "role_name": "大鲨鱼",
+        "role_vip": "23",
+        "server_id": "55469563",
+        "server_name": "主宰服",
+        "sponsor_level": "12",
+        "trans_level": "5"
+    }
+}
+```
+
+调用方法：String setting=上面示例JSON
+
+```
+GameSdk.getInstance().putRoleReport(setting, new SubmitRoleInfoCallBack() {
+            @Override
+            public void onSuccess(Object o) {
+
+                showToast(o.toString()+"");
+            }
+
+            @Override
+            public void onFailure(int code, String msg) {
+
+            }
+        });
+
+```
+
+| 参数 | 类型 | 是否必须 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| event | String | true | other | 事件类型 |
+| server\_id | String | true | \- | 区服ID |
+| server\_name | String | true | \- | 区服名称 |
+| cp\_role\_id | String | true | \- | 游戏方角色ID |
+| role\_name | String | true | \- | 游戏角色名称 |
+| role\_level | int | true | \- | 角色等级 |
+| cp\_account | String | false | \- | cp账号 |
+| role\_vip | int | false | 0 | 角色VIP等级(赞助等级) |
+| combat\_num | String | false | "0" | 角色战力 |
+| reiki\_num | int | false | 0 | 角色灵符值 |
+| online\_time | int | false | 0 | 本次在线时长 |
+| attack | int | false | 0 | 攻击力 |
+| profession | String | false | \- | 职业 |
+| gang\_name | String | false | \- | 帮会(行会)名称 |
+| trans\_level | int | false | 0 | 转生等级 |
+
+特殊说明：事件类型event说明：
+
+| EVENT | 说明 |
+| --- | --- |
+| create | 创建角色 |
+| online | 角色上线 |
+| offline | 角色下线 |
+| level\_up | 角色升级 |
+| delete | 删除角色 |
+| recharge | 角色充值 |
+| other | 其他 |
+
+2.8、游戏角色行为上报接口（按需接入）
+
+示例：
+
+```
+{
+    "cp_role_id": "93478561",
+    "event": "coin_get",
+    "querys": [
+        {
+            "name": "角色具体信息0",
+            "value": "0"
+        },
+        {
+            "name": "角色具体信息1",
+            "value": "1"
+        },
+        {
+            "name": "角色具体信息2",
+            "value": "2"
+        },
+        {
+            "name": "角色具体信息3",
+            "value": "3"
+        },
+        {
+            "name": "角色具体信息4",
+            "value": "4"
+        }
+    ],
+    "role_name": "张飞"
+}
+```
+
+```
+ GameService.getInstance().putGameRoleport(param, new ZyListener() {
+            @Override
+            public void Success(Object s) {
+
+            }
+
+            @Override
+            public void Error(Object s) {
+
+            }
+        });
+
+```
+
+字段说明：
+
+| 字段 | 是否必须 | 类型 | 说明 |
+| --- | --- | --- | --- |
+| event | true | String | 事件类型 |
+| server\_id | true | String | 区服ID |
+| cp\_role\_id | true | String | CP角色ID |
+| role\_name | true | String | 角色名称 |
+| querys | true | Array | 属性 |
+| querys.name | true | String | 属性名 （中文） |
+| querys.value | true | String | 属性值 |
+
+EVENT枚举说明：
+
+| EVENT | 说明 |
+| --- | --- |
+| coin\_get | 货币产出 |
+| coin\_cost | 货币消耗 |
+| item\_get | 道具产出 |
+| item\_cost | 道具消耗 |
+| shop | 商城购买 |
+| task\_complete | 任务完成 |
+| newplayer\_guide | 新手指引 |
+| mail | 邮件操作 |
+
+2.9、SDK退出程序
+
+在返回键处理时
+
+```
+   @Override
+    public void onBackPressed() {
+       GameAdService.getInstance().exitApp();
+
+    }
+```
+
+2.9.1、游戏排行榜
+
+参数示例：
+
+```json
+{
+    "cp_role_id": "w55231582254",
+    "server_name": "test",
+    "server_id": "test",
+    "role_name": "test"
+}
+```
+
+```
+GameAdService.getInstance().onStartRanking(json)
+```
+
+| 参数 | 是否必须 | 说明 |
+| --- | --- | --- |
+| cp\_role\_id | true | CP角色ID |
+| server\_name | true | 区服名称 |
+| server\_id | true | 区服ID |
+| role\_name | true | 游戏角色名称 |
+
+2.3.0、游戏内有切换账号按钮，调用outGameLogin方法（没有此功能无需调用）选择使用,退出登录成功后再初始化SKD方法中监听回调信息，状态码3，游戏调用了此方法，SDK会自动弹出登
+
+```
+GameAdService.getInstance().outGameLogin(new OnLogoutListener() {
+            @Override
+            public void logoutSuccess(Object s) {
+
+
+            }
+
+            @Override
+            public void logoutError(Object s) {
+
+            }
+        });
+
+```
+
+三：广告集成
+
+3.1、初始化广告
+
+```
+  GameAdService.getInstance().initAdvertisement(this);
+```
+
+3.2、SDK拉起广告预加载（在登录后并且初始化了广告SDK）
+
+参数示例：
+
+```json
+{
+    "ad_scene_id": "01255", //广告场景ID
+    "advertiser_type": "2"// 广告类型 1 banner广告 2 激励广告   3  插屏广告  4 格子广告 5 原生广告
+}
+```
+
+```
+  GameAdService.getInstance().loadAd(json,GameSDKListener);
+
+
+```
+
+| 参数 | 说明 |
+| --- | --- |
+| ad\_scene\_id | 广告场景ID |
+| advertiser\_type | 告类型 1 banner广告 2 激励广告   3  插屏广告  4 格子广告 5 原生广告 |
+
+返回JSON说明
+
+```json
+{
+    "eventType": "ad_play_start",
+    "msg": "广告播放开始",
+    "adInfo": {
+        "id": "79453c504021bf661f98635ff369051e_11702243_1763381505236",
+        "publisher_revenue": 0.0006101089764999999,
+        "publisher_revenue_cny": 0.00061,
+        "currency": "CNY",
+        "country": "CN",
+        "adunit_id": "b69115878bc6eb",
+        "adunit_format": "RewardedVideo",
+        "precision": "exact",
+        "network_type": "Network",
+        "network_placement_id": "4253111318032105",
+        "ecpm_level": 0,
+        "segment_id": 0,
+        "scenario_id": "01255",
+        "scenario_reward_name": "reward_item",
+        "scenario_reward_number": 1,
+        "network_firm_id": 8,
+        "adsource_id": "11702243",
+        "adsource_index": 0,
+        "adsource_price": 0.6101089765,
+        "adsource_price_cny": 0.61,
+        "adsource_isheaderbidding": 1,
+        "ext_info": {
+            "mp": -1,
+            "is_reward_ad": false,
+            "click_dev_extra": {
+
+            },
+            "request_id": "v37fdogc34iys01",
+            "token": "",
+            "exp_dev_extra": {
+
+            }
+        },
+        "reward_custom_data": "",
+        "abtest_id": 755106,
+        "placement_type": 1,
+        "bid_floor": 0,
+        "ad_source_type": 1,
+        "ad_source_custom_ext": "",
+        "url_tag_params": "{}",
+        "network_name": "Tencent Ads",
+        "show_custom_ext": "",
+        "s_id": 0,
+        "req_id": "79453c504021bf661f98635ff369051e",
+        "bid_type": 2
+    },
+    "placementId": "b69115878bc6eb"
+}
+```
+
+eventType说明
+
+| 参数 | 说明 |
+| --- | --- |
+| auto\_load\_success | 自动加载成功 |
+| auto\_load\_fail | 自动加载失败 |
+| ad\_not\_ready | 广告未准备好 |
+| ad\_play\_start | 广告播放开始 |
+| ad\_play\_end | 广告播放结束 |
+| ad\_play\_fail | 广告播放失败 |
+| ad\_closed | 广告已关闭 |
+| ad\_clicked | 广告点击 |
+| reward\_received | 收到的奖励 |
+| reward\_failed | 奖励失败 |
+| ad\_ready | 广告准备就绪 |
+| ad\_again\_play\_start | 广告再次播放开始 |
+| again\_reward\_received | 再次收到奖励 |
+
+3.3、显示广告
+
+```
+  GameAdService.getInstance().showAd();
+```
+
+四：Activity生命周期
+
+```
+  GameAdService.getInstance().onDestroy(this);
+```
+
+五：服务端接口   调用方直接使用http 调用接口
+
+接口地址：【POST】 /android\_sdk/auth/checkLogin
+
+请求头参数
+
+| 参数 | 必选 | 参数值 | 说明 |
+| --- | --- | --- | --- |
+| Content-Type | true | application/json |  |
+| User-Token | true |  | 登录后由 SDK 返回的user\_token |
+
+Body:
+
+| 参数 | 必选 | 类型 | 说明 |
+| --- | --- | --- | --- |
+| game\_id | true | int | 游戏接入时分配的游戏ID(建议从user\_token中取，#后面的数字即为game\_id) |
+| player\_id | true | int | 游戏登录后由 SDK 返回的player\_id |
+| sign | true | String | 参数签名 |
+
+返回参数：
+
+| 参数 | 必须 | 类型 | 说明 |
+| --- | --- | --- | --- |
+| status\_code |  | int | 状态码   1 正常在线，否则不允许登录 |
+| msg |  |  |  |
+| data | false | \[\] | 返回数据（空） |
+
+调用方检测当前用户是否登录过，在线状态； 如果返回参数不是正常登录则不允许登录游戏
+
+请求示例：
+
+```
+<php?
+  public function checkLogin(){
+     $host = 'https://zyouapi.wozhangwan.com';
+     $checkLoginUrl = '/android_sdk/auth/checkLogin';
+     $url = $host.$checkLoginUrl;
+     $gameSecret = "game_secret";
+     $body = ["player_id" => 1245, "game_id" => 14];
+     $userToken = "user_token";
+     $body["sign"] = makeSign($body, $gameSecret);
+     $headers = ["Content-Type:application/json","User-Token:".$userToken];
+     $response = curl_post($url, $body, $hearders);
+  }
+
+ public function makeSign($params,$gameSecret){
+        $signStr = '';
+        ksort($params, SORT_REGULAR);
+        foreach ($params as $key => $val) {
+            if (is_array($val)) {
+                ksort($val, SORT_REGULAR);
+                $val = json_encode($val, JSON_UNESCAPED_UNICODE);
+            }
+            $signStr .= $key . '=' . $val . '&';
+        }
+        $signStr .= 'game_secret=' . $gameSecret;
+        return md5($signStr);
+  }
+
+  public function curl_post($url, $body, $headers){
+    //初始化
+     $curl  =  curl_init ( );
+     //设置抓取的url
+     curl_setopt ( $curl, CURLOPT_URL ,  $url);
+     //设置头文件的信息作为数据流输出
+     curl_setopt ( $curl, CURLOPT_HEADER ,  1 );
+     //设置获取的信息以文件流的形式返回，而不是直接输出。
+     curl_setopt ( $curl, CURLOPT_RETURNTRANSFER ,  1 );
+     //设置post方式提交
+     curl_setopt ( $curl, CURLOPT_POST ,  1 );
+     //设置post参数
+     curl_setopt ( $curl, CURLOPT_POSTFIELDS ,  json_encode($body) );
+     //设置请求头
+     curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
+     //执行命令
+     $data  =  curl_exec ( $curl );
+     //关闭URL请求
+     curl_close ( $curl );
+     //显示获得的数据
+     return json_decode($data, true);
+    }
+
+```
\ No newline at end of file