幫助文檔


版本號
修改日期
更新內容
V1.2.0 2014-12-25 創建文檔
V1.2.0 2015-02-10
修改完善所有接口的接入點說明
V1.3.0
2015-03-05 一、統計接口調整:
去掉(除登錄,創建角色)其他接口重複的字段:用戶唯一標識,服務器ID,角色唯一標識

二、修改androidsManifest.xml:
  1.將meta節點name為statistic_serverurl去掉,添加為HJR_DATA_URL_DEBUG模式
   2.將meta節點name為gamekey改為HJR_GAMEKEY
   3.將meta節點name為channel改為:HJR_CHANNEL

三、所有統計數據接口添加重發機製
V1.3.1
2015-04-10 更新優化,修複bug




一.SDK構成

    當下載完統計平台sdk包解壓之後,看到的資源如下圖

    圖片1.png

    上圖的資源說明:

1.  HJR_Java_Data_1.3.1:統計sdk測試demo

2.  libs:工程依賴的 libs 包,同HJR_Java_Data_1.3.1裏麵的libs裏麵的文件,解壓後將此文件夾裏麵的內容拷貝

          到遊戲工程的相同libs目錄下

3.  1.3.0更新到1.3.1注意事項.txt:更新sdk時需要修改的地方

4.  androidsManifest.xml 配置.txt :androidsManifest.xml的配置說明文件

5.  HJR_Java_Data_1.3.1接入文檔規規範.pdf:統計sdk接入說明文檔

二、SDK植入步驟

       

    第一步:植入sdk前,請確保到平台下麵已經申請好遊戲密鑰(gamekey)和下載最新的統計sdk版本了


    第二步:解壓HJR_Java_Data_1.3.1.zip ,進入 libs ,將libs裏麵的所有資源(即下圖所示的資源)拷貝到遊戲工程的 libs 目錄下


    圖片2.png

    

    第三步:配置構建路徑。Eclipse用戶右鍵工程根目錄,選擇Properties -> Java Build Path -> Libraries,然後點擊Add External JARs... 選擇指向jar的路徑,點擊OK,在Properties -> Java Build Path -> Order and Export裏麵勾選中圖中添加的jar包,點擊ok即導入成功

   3.png

                    

    圖片1.png



    注意: Eclipse ADT 17 以上版本用戶,請在工程目錄下建一個文件夾libs,把jar包直接拷貝到這個文件夾下,刷新下 Eclipse中工程就好了。 不要通過上述步驟手動配置構建路徑的方式引入Jar包。

            詳情請參考: Dealing with dependencies in androids projects


    第四步:將 "androidsManifest.xml配置.xml” 文件中的內容配置到遊戲的androidsManifest.xml

     配置說明:

    1.在<application>節點外添加permission配置:

            <uses-permission androids:name="androids.permission.ACCESS_WIFI_STATE"/>

            <uses-permission androids:name="androids.permission.ACCESS_NETWORK_STATE"/>

            <uses-permission androids:name="androids.permission.INTERNET"/>

            <uses-permission androids:name="androids.permission.CHANGE_NETWORK_STATE"/>

            <uses-permission androids:name="androids.permission.CHANGE_WIFI_STATE" />

 

    2.在<application>節點下,添加 meta-data 配置:

            <!-- 遊戲密鑰gamekey,需要遊戲申請-->

            <meta-data

                androids:name="HJR_GAMEKEY"

            androids:value="申請的gamekey" />

     

            <!-- 渠道號   注意格式必須為\+空格+渠道號(flashAIR的遊戲除外-->

            <meta-data

                androids:name="HJR_CHANNEL"

            androids:value="\ 自定義的渠道號" />

             

            <!--測試環境請將DEBUG必須為true;正式上線請改為false,否則影響上線統計數據-->

            <meta-data androids:name="HJR_DATA_URL_DEBUG" androids:value="true"/>


    3.配置示例如下圖:

      注意:一定要在<application>節點下配置meta-data節點,否則會導致統計不上數據


圖片1.png

    第五步:調用基本代碼,在調用的Activity裏麵添加引用代碼:


            import com.sdkkit.gameplatform.statistic.SDKKitStatisticSDK;

            import com.sdkkit.gameplatform.statistic.util.C;

            import com.sdkkit.gameplatform.statistic.util.InitListener;

            import com.sdkkit.gameplatform.statistic.util.ProtocolKeys;


        (調用的接口具體詳見下麵:三、SDK接口調用說明)

 


三、SDK接口調用說明

1.  SDK初始化接口(必接)

    接入點說明:在一個遊戲啟動的時候,即通常在啟動的第一個ActivityonCreate方法裏麵調用

    Map<String, Object> params = new HashMap<String, Object>() ; 

    //遊戲類型 : 1, 網遊 ; , 單機

    params.put(ProtocolKeys.KEY_GAMETYPE, "1");

    

    SDKKitStatisticSDK.getInstance().init(this,params, new InitListener() {

                @Override

                public void onSuccess() {

                System.out.println(初始化成功......");

                }

                

                @Override

                public void onFailed() {

                System.out.println(初始化失敗......");

                }

                });



2.登錄接口(必接)

    接入點說明:在登錄完成並且成功選擇區服之後調用

    Map<String, Object> params = new HashMap<String, Object>();

    //必填,用戶標識 : 傳入用戶ID即可 ,*請注意:平台標識,不能為中文或中文類型的特殊字符

    params.put(ProtocolKeys.KEY_USERMARK,"loginUserId");

    //可選,整型(int(3)),用戶類型:0為 臨時用戶,1為注冊用戶,2為第三方登錄用戶,遊戲沒有此字段的可不填

    params.put(ProtocolKeys.KEY_USERTYPE,2);

    //網遊必填, 服務器編號,不能為中文或中文類型的特殊字符

    params.put(ProtocolKeys.KEY_SERVERNO"10");


    SDKKitStatisticSDK.getInstance().doUserLogin(params);

    參數說明:

    ProtocoKeys.KEY_USERMARK:用戶標識(必填),傳入用戶ID即可,*請注意:
        ProtocoKeys.KEY_USERTYPE:用戶類型(可選),不能為中文或中文類型的特殊字符
        ProtocoKeys.KEY_SERVERNO :服務器ID(網遊必填) ,不能為中文或中文類型的特殊字符

        備注:1. 用戶標識實際的形式為:用戶ID@平台 標識;其中平台 標識,不能為中文或中文類型的特殊字符;

                            @平台標識:可不填寫,後台已自動拚接,以區分不同渠道平台的用戶,對接方也可自定填寫 不影響統計
                  2. 所有的非本平台渠道的遊戲,填寫用戶類型:ProtocolKeys.KEY_USERTYPE,值為2,均為第三方平台的用戶

             

3.創建角色接口(必接)

    接入點說明:在遊戲裏用戶登錄選擇區服進入遊戲並創建角色成功之後調用

    Map<String, Object> params = new HashMap<String, Object>();

    //網遊必填,角色唯一標識,不能為中文或中文類型的特殊字符

    params.put(ProtocolKeys.KEY_ROLEMARK"roleMark");

    

    SDKKitStatisticSDK.getInstance().doCreateRole(params);

    參數說明:

    ProtocoKeys.KEY_ ROLEMARK: 角色標識(網遊必填) ,不能為中文或中文類型的特殊字符

 

4.提交訂單接口(必接)

    接入點說明:1.在支付成功之後調用

    (參數ProtocolKeys.KEY_AMOUNT的值以最終支付成功收到通知的實際金額為準,否則影響統計)

    Map<String, Object> params = new HashMap<String, Object>();

    //必填,支付方式,可為中文

    params.put(ProtocolKeys.KEY_PAYNAME"支付寶");

    //必填,充值金額(人民幣,單位:元),不能為中文或中文類型的特殊字符

    params.put(ProtocolKeys.KEY_AMOUNT"12");

    //必填,訂單號,不能為中文或中文類型的特殊字符

    params.put(ProtocolKeys.KEY_ORDERNUMBER"11100");

    //網遊必填,整型(int),玩家等級

    params.put(ProtocolKeys.KEY_UPGRADE,4);

    //可選,商品描述,可為中文

    params.put(ProtocolKeys.KEY_PRODUCT_DESC"這裏是我的商品描述");

    

    SDKKitStatisticSDK.getInstance().doPostOrder(params) ;

    參數說明:

    ProtocolKeys.KEY_PAYNAME:支付方式(必填)可為中文

    ProtocolKeys.KEY_AMOUNT充值金額(必填)金額為人民幣(單位:元),不能為中文或中文類型的特殊字符

    ProtocolKeys.KEY_ORDERNUMBER訂單號(必填)不能為中文或中文類型的特殊字符

    ProtocolKeys.KEY_UPGRADE玩家等級(網遊必填整型(int),

    ProtocolKeys.KEY_PRODUCT_DESC商品描述(可選)可為中文

 

 

 

5.玩家升級接口(必接)

        接入點說明:在登錄遊戲成功,並且成功選擇區服後,當拿到用戶的遊戲等級信息時,請調用“玩家升級“接口

    Map<String, Object> params = new HashMap<String, Object>();

    //必填,整型(int),玩家等級

    params.put(ProtocolKeys.KEY_UPGRADE, 2);

    SDKKitStatisticSDK.getInstance().doUserUpgrade(params);

    參數說明:

    PotocolKeys.KEY_UPGRADE玩家等級(必填)整型(int)

 

 

6.獲得道具接口(必接)

    接入點說明:在遊戲裏麵獲取道具之後調用

    Map<String, Object> params = new HashMap<String, Object>();

    //必填,道具唯一標識,不能為中文或中文類型的特殊字符

    params.put(ProtocolKeys.KEY_ITEMID"3");

    //必填,道具類型,不能為中文或中文類型的特殊字符

    params.put(ProtocolKeys.KEY_ITEMTYPE"2");

    //必填,整型(int),道具數量

    params.put(ProtocolKeys.KEY_ITEMCOUNT1);

    //可選,原因,可為中文

    params.put(ProtocolKeys.KEY_REASON"原因");

    SDKKitStatisticSDK.getInstance().doItemGet(params);

    參數說明:

    PotocolKeys.KEY_ITEMID道具唯一標識(必填),不能為中文或中文類型的特殊字符

    PotocolKeys.KEY_ITEMTYPE道具類型(必填),不能為中文或中文類型的特殊字符

    PotocolKeys.KEY_ITEMCOUNT道具數量(必填), 整型(int)

    PotocolKeys.KEY_REASON原因(可選),可為中文

 

 

7.使用道具接口(必接)

    接入點說明:在遊戲裏麵使用道具之後調用

    Map<String, Object> params = new HashMap<String, Object>();

    //必填,道具唯一標識,不能為中文或中文類型的特殊字符

    params.put(ProtocolKeys.KEY_ITEMID"3");

    //必填,道具類型,不能為中文或中文類型的特殊字符

    params.put(ProtocolKeys.KEY_ITEMTYPE,"2");

    //必填,整型(int)道具數量

    params.put(ProtocolKeys.KEY_ITEMCOUNT, 1);

    //可選,原因,可為中文

    params.put(ProtocolKeys.KEY_REASON"原因");

    SDKKitStatisticSDK.getInstance().doItemConsume(params);

 

    參數說明:

    PotocolKeys.KEY_ITEMID道具唯一標識(必填),不能為中文或中文類型的特殊字符

    PotocolKeys.KEY_ITEMTYPE道具類型(必填),不能為中文或中文類型的特殊字符

    PotocolKeys.KEY_ITEMCOUNT道具數量(必填), 整型(int)

    PotocolKeys.KEY_REASON原因(可選),可為中文

     

 

8.購買道具接口(必接)

    接入點說明:在遊戲裏麵購買道具之後調用

    

    Map<String, Object> params = new HashMap<String, Object>();

    //必填,道具唯一標識,不能為中文或中文類型的特殊字符

    params.put(ProtocolKeys.KEY_ITEMID"3");

    //必填,道具類型,不能為中文或中文類型的特殊字符

    params.put(ProtocolKeys.KEY_ITEMTYPE"3");

    //必填,整型(int),道具數量

    params.put(ProtocolKeys.KEY_ITEMCOUNT, 1);

    //必填,整型(int),虛擬幣數量

    params.put(ProtocolKeys.KEY_CURRENCYCOUNT,1);

    //必填,虛擬幣類型,可為中文

    params.put(ProtocolKeys.KEY_CURRENCYTYPE"1");

    //可選,計費點,可為中文

    params.put(ProtocolKeys.KEY_POINT"");

     

    SDKKitStatisticSDK.getInstance().doItemBuy(params);

    參數說明:

    PotocolKeys.KEY_ITEMID道具唯一標識(必填),不能為中文或中文類型的特殊字符

    PotocolKeys.KEY_ITEMTYPE道具類型(必填),不能為中文或中文類型的特殊字符

    PotocolKeys.KEY_ITEMCOUNT道具數量(必填), 整型(int)

    ProtocolKeys.KEY_CURRENCYCOUNT:虛擬幣數量(必填), 整型(int),填寫總數

    PotocolKeys.KEY_CURRENCYTYPE虛擬幣類型(必填),可為中文

    PotocolKeys.KEY_POINT計費點(可選),可為中文

 

9.開始關卡接口(必接)

    接入點說明:在遊戲的每個關卡開始的時候調用

    

    Map<String, Object> params = new HashMap<String, Object>();

     

    //必填,玩家等級,整型(int)

    params.put(ProtocolKeys.KEY_GRADE1);

    //必填,關卡序號,整型(int)

    params.put(ProtocolKeys.KEY_SEQNO, 1);

    //必填,關卡唯一標識,不能為中文或中文類型的特殊字符

    params.put(ProtocolKeys.KEY_LEVELID,  "levelMark");

    //必填,整型(int),關卡難度:0.簡單1.一般2.困難,3.很困難,4.非常困難(以此類推,越難的排後,數字遞增)

    params.put(ProtocolKeys.KEY_DIFFICULTY1);

     

     

    SDKKitStatisticSDK.getInstance().doStartLevel(params);

    參數說明:

    PotocolKeys.KEY_GRADE: 玩家等級(必填),整型(int)

    PotocolKeys.KEY_SEQNO: 關卡序號(必填)整型(int)

    PotocolKeys.KEY_LEVELID: 關卡唯一標識(必填),不能為中文或中文類型的特殊字符

      PotocolKeys.KEY_DIFFICULTY:關卡難度(必填), 整型(int):0.簡單,1.一般,2.困難,3.很困難,4.非常困難(以此

                                                             類推,越難的排後,數字遞增)

 

 

 

10.結束關卡接口(必接)

    接入點說明:在遊戲的每個關卡結束的時候調用

    Map<String, Object> params = new HashMap<String, Object>();

    //必填,關卡序號,整型(int)

    params.put(ProtocolKeys.KEY_SEQNO, 1);

    //必填,關卡唯一標識,不能為中文或中文類型的特殊字符

    params.put(ProtocolKeys.KEY_LEVELID,  "levelMark");

    //必填,整型(int),關卡狀態: 0.成功, 2失敗,3退出 ;此處固定隻能填0,或2,或3,填其他數字會導致沒有統計數據或統計出錯

    params.put(ProtocolKeys.KEY_STATUS, 2);

    //可選,原因(如失敗點),可為中文

    params.put(ProtocolKeys.KEY_REASON"失敗點");

    SDKKitStatisticSDK.getInstance().doEndLevel(params);

     

    參數說明:

    PotocolKeys.KEY_GRADE: 玩家等級(必填),整型(int)

    PotocolKeys.KEY_SEQNO: 關卡序號(必填)整型(int) 

      PotocolKeys.KEY_STATUS整型(int),關卡狀態(必填): 0.成功, 2失敗,3退出 ;此處固定隻能填0,或2,或3,填

                                                        其他數字會導致沒有統計數據或統計出錯

    PotocolKeys.KEY_REASON原因(如失敗點)(可選),可為中文

 

11. 按鈕點擊接口(非必接)

    接入點說明:在用戶完成按鈕點擊之後,如:登錄、進入遊戲,充值等。

    Map<String, Object> params = new HashMap<String, Object>();

    //必填,按鈕名稱,可為中文

    params.put(ProtocolKeys.KEY_NAME"按鈕名稱");

    

    SDKKitStatisticSDK.getInstance().doGameClick(params);

    參數說明:PotocolKeys.KEY_NAME按鈕名稱(必填), 可為中文

  

 

四、遊戲在線時長統計及釋放資源技術解決方案(必接)

如果你的工程中有Activity基類(如BaseActivity),那麽重寫此基類的onStop()方法和onResume()方法,如下

       /**遊戲回到前台*/

          @Override

          protected void onResume() {

          super.onResume();

               if (!C.isActive) {

                                SDKKitStatisticSDK.getInstance().saveFrontTime();

                                C.isActive = true ;

                        } 

                          }

 

        /**遊戲進入後台*/

           @Override

           protected void onStop() {

     super.onStop();

               if (!SDKKitStatisticSDK.getInstance().isAppOnForeground()) {

                            SDKKitStatisticSDK.getInstance().saveBackTime() ;

                            C.isActive = false ;

                    } 

                                                          }

 

 

如果你的工程中沒有做 Activity 基類,那麽你需要編寫基類 BaseActivity,並且你的其他 Activity都要繼承這個類,BaseActivity 如下:

            public class BaseActivity extends Activity {

            @Override

            protected void onStop() {

                super.onStop();

 

            if (!SDKKitStatisticSDK.getInstance().isAppOnForeground()) {

                            SDKKitStatisticSDK.getInstance().saveBackTime() ;

                            C.isActive = false ;

                    } 

                      }

                  @Override

            protected void onResume() {

                  super.onResume();

                            if (!C.isActive) {

                            SDKKitStatisticSDK.getInstance().saveFrontTime();

                            C.isActive = true ;

                            } 

                            }

                            }

        (接入點說明:此功能是為了統計遊戲在線時間,如果你的遊戲中實現了統計在線時間的方法,那麽不用做以上操

作,隻需要在你的遊戲進入後台和回到前台的方法中調用統計接口即可:

    遊戲進入後台調用:

    SDKKitStatisticSDK.getInstance().saveBackTime() ;

    遊戲回到前台調用:

    SDKKitStatisticSDK.getInstance().saveFrontTime();

 

 

 

 

五、捕獲並處理全局異常技術解決方案(非必接)

    如果你的工程中有繼承了 Application 的類,那麽在此類的 onCreate()方法中添加如下內容:

          // 異常處理,不需要處理時注釋掉這兩句即可!

    CrashHandler crashHandler = CrashHandler.getInstance();

    // 注冊 crashHandler

    crashHandler.init(getApplicationContext());

如果你的工程中沒有繼承 Application 的類,那麽在你工程主包名目錄下建立一個繼承 Application的類,名稱

App,並在 androidsManifest.xml 中注冊此 Application 類,即在<application>中添加 name屬性,示例代

碼如下:

        <application

        androids:name="App"

        androids:icon="@drawable/ic_launcher"

        androids:label="/app_name"

        androids:theme="@androids:style/Theme.Light.NoTitleBar.Fullscreen">

        </application>

     

    App 類的調用示例代碼如下:

    public class App extends Application {

    @Override

    public void onCreate() {

    super.onCreate();

    // 異常處理,不需要處理時注釋掉這兩句即可!

    CrashHandler crashHandler = CrashHandler.getInstance();

    // 注冊 crashHandler

    crashHandler.init(getApplicationContext());

    }

                }

     

     

六、SDK對接注意事項

        1.HJR_GAMEKEY  :  需要向統計sdk平台申請正式的gamekey;

  HJR_CHANNEL注意格式必須為\+空格+渠道號(flashAIR的遊戲除外),不同渠道平台填寫的渠道號以區分

                                 平台,這個不需要向統計sdk平台申請,自定義填入

         HJR_DATA_URL_DEBUG:是否為測試模式,遊戲正式上線之前為ture正式上線請改為false


        2.請所有的接口調用處嚴格按照“接入點說明”接入,隻有確保準確的統計數據,才能正式上線


        3.所有接口的用戶唯一標識 (ProtocolKeys.KEY_USERMARK),其後台格式為:

          用戶ID@平台唯一標識

          用戶ID:為用戶登錄之後獲取的userId

          平台標識:為接入的不同渠道平台的唯一標識,此標識統一由後台自動拚接,不用自定義傳入


        4.所有的必填項必須按照要求填寫,尤其不能填寫中文或中文字符的,填寫了會導致統計出錯


        5.結束關卡接口中的狀態必須按照固定整型0,2,3填寫,否則統計出錯

     

     

     

七、接入驗證(兩種方式,推薦方式一)

  方式一

    1.瀏覽器中輸入地址:http://open.kuaifazs.com/,輸入自己注冊的賬號密碼登錄,如下圖所示:

        3.png


    2.進入登錄之後的頁麵,點擊選中自己的遊戲,出現下拉菜單,點擊”數據統計“ ,如下圖所示:

        圖片1.png


3.進入遊戲統計分析頁麵之後,點擊”實時日誌“選項,如下圖所示:

        圖片1.png


    4.進入自己的遊戲統計數據測試頁麵,如下圖所示:

    圖片1.png


方式二

    1.瀏覽器輸入下麵的地址:

    測試分析頁麵(meta-data裏麵的HJR_DATA_URL_DEBUGture)

        http://test.d.haojieru.com/test/analysis.php?gamekey=申請的gamekey

     

     

     

    正式分析頁麵(meta-data裏麵的HJR_DATA_URL_DEBUGfalse)

    http://d.haojieru.com/test/analysis.php?gamekey=申請的gamekey

     

 

 

    例:分析頁麵之登錄分析顯示如下圖:

圖片1.png

    分析頁麵需要關注的接口和對應的url參考如下:

    1) 登錄——/user/login/

    2) 創建角色——/user/createrole/

    3) 提交訂單——/order/submit/

    4) 遊戲按鈕點擊——/sys/gamebtnclick/

    5) 玩家升級——/user/upgrade/

    6) 購買道具——/item/buy/

    7) 獲得道具——/item/get/

    8) 使用道具——/item/consume/

    9) 開始關卡——/level/pass/

    10) 結束關卡——/level/pass/ 

    11) 在線時長——/sys/gamedeactivate(acitivity生命周期自動調用的)

    前11個為接入驗證的接口,下麵的12-14號接口為後台自動調用的接口

    12) 遊戲激活——/sys/gamestart/(初始化後台自動調用)

    13) 公網ip——/sys/net/(初始化後台自動調用)

    14) 異常記錄——/sys/abnormal(程序發生異常時後台自動調用,可看到程序異常日誌代碼)

    注意:所有的接口14除外:隻有顯示“操作成功”才算調用成功