Quick Tracking：YonBuilder SDK

qtAnalytics 原生外掛程式使用攻略

1.使用之前須從QuickTracking申請帳號並建立應用，擷取 appkey 和收數網域名稱。

QuickTracking官網接入流程參考

2.配置 config.xml 檔案，配置完畢後需通過雲端編譯生效，配置方法如下：

• 名稱：qtAnalytics

• 參數：ios_appkey、ios_channel、android_appkey、android_channel、primaryDomain、standbyDomain

• 配置樣本:

<feature name="qtAnalytics">
  <param name="ios_appkey" value="YOUR_IOS_APP_KEY"/>
  <param name="ios_channel" value="YOUR_IOS_CHANNEL"/>
  <param name="android_appkey" value="YOUR_ANDROID_APP_KEY"/>
  <param name="android_channel" value="YOUR_ANDROID_CHANNEL"/>
  <param name="primaryDomain" value="YOUR_primaryDomain"/>
  <param name="standbyDomain" value="YOUR_standbyDomain"/>
</feature>

• 欄位描述:

  1. ios_appkey：iOS App的Key。

  2. ios_channel：iOS渠道號。

  3. android_appkey：Android App的Key。

  4. android_channel：Android渠道號。

  5. primaryDomain：收數主網域名稱。

  6. standbyDomain：收數副網域名稱。

原生外掛程式介面

初始化介面

init

參數

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.init(
    {logEnabled:true},
    function(ret, err) {
        if (ret.status) {
            api.alert({
                msg: JSON.stringify(ret)
            })
        } else {
            api.alert({
                msg: JSON.stringify(err)
            })
        }
    }
);

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

關閉採集

disableSDK

• 考慮到app端上有隱私權原則操作流程式控制制，因此 sdk 對開啟、關閉標識沒有額外的緩衝狀態控制，即如果本次冷啟動後關閉SDK功能後希望每次冷啟動都是關閉採集的狀態，需業務研發主動調用 disableSDK API 功能

• 由於iOS sdk 應用生命週期內僅能初始化一次，並且初始化情境依賴於網路和服務端通訊，因此再調用 SDK 關閉、開啟功能時，需要有如下情境使用注意：

  

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.disableSDK();

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

開啟SDK

enableSDK

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.enableSDK();

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

路徑設定

resetStorePath

注意，需要檢查目前是否已經使用了友盟+SDK，如果已經使用，請務必設定更改SDK檔案路徑。

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.resetStorePath();

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

自訂安卓裝置標識符

setAndroidDeviceInfo

SDK實現了預設的裝置標識符採集，此預設實作類別預設會採集如下標識。

如果開發人員希望針對上表中的某幾個裝置標識符採集行為做控制，如：不採集IMEI欄位和Serial欄位，自行實現OAID的採集方法。就可以自訂這幾個欄位

注意：

1. 如果不進行自訂，則預設由QuickTracking SDK採集。

2. 請在調用SDK初始化函數之前，先調用setAndroidDeviceInfo設定函數

3. 如果不需要對裝置標識採集行為做控制，就不需要調用

參數

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.setAndroidDeviceInfo({
    IMEI:null,
    Serial:null,
    OAID:"custom_oaid"
});
qtAnalytics.init(
    {logEnabled:true},
    function(ret, err) {
        if (ret.status) {
            api.alert({
                msg: JSON.stringify(ret)
            })
        } else {
            api.alert({
                msg: JSON.stringify(err)
            })
        }
    }
);

可用性

Android系統

可提供的1.0.0及更高版本

自訂idfa

customSetIdfa

自訂設定idfa,不採集可返回 ''

注意：請謹慎決定是否實現對應方法，一旦你選擇在自己實現採集方法，此裝置標識的採集工作就由你全權接管了，SDK不會再試圖採集此裝置標識。SDK能採集到的裝置標識越少，對統計資料的準確性和穩定性負面影響越大

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.customSetIdfa({
    idfa: ''
});

可用性

iOS系統

可提供的1.0.0及更高版本

自訂idfv

customSetIdfv

自訂設定idfv,不採集可返回 ''

注意：請謹慎決定是否實現對應方法，一旦你選擇在自己實現採集方法，此裝置標識的採集工作就由你全權接管了，SDK不會再試圖採集此裝置標識。SDK能採集到的裝置標識越少，對統計資料的準確性和穩定性負面影響越大

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.customSetIdfv({
    idfv: ''
});

可用性

iOS系統

可提供的1.0.0及更高版本

自訂openUdid

customSetOpenUdid

自訂設定openUdid,不採集可返回 ''

注意：請謹慎決定是否實現對應方法，一旦你選擇在自己實現採集方法，此裝置標識的採集工作就由你全權接管了，SDK不會再試圖採集此裝置標識。SDK能採集到的裝置標識越少，對統計資料的準確性和穩定性負面影響越大

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.customSetOpenUdid({
    openUdid: ''
});

可用性

iOS系統

可提供的1.0.0及更高版本

自訂utdid

customSetUtdid

自訂設定utdid,不採集可返回 ''

注意：請謹慎決定是否實現對應方法，一旦你選擇在自己實現採集方法，此裝置標識的採集工作就由你全權接管了，SDK不會再試圖採集此裝置標識。SDK能採集到的裝置標識越少，對統計資料的準確性和穩定性負面影響越大

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.customSetUtdid({
    utdid: ''
});

可用性

iOS系統

可提供的1.0.0及更高版本

自訂mcc

customSetMcc

自訂設定mcc,不採集可返回 ''

注意：請謹慎決定是否實現對應方法，一旦你選擇在自己實現採集方法，此裝置標識的採集工作就由你全權接管了，SDK不會再試圖採集此裝置標識。SDK能採集到的裝置標識越少，對統計資料的準確性和穩定性負面影響越大

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.customSetMcc({
    mcc: ''
});

可用性

iOS系統

可提供的1.0.0及更高版本

自訂mnc

customSetMnc

自訂設定mnc,不採集可返回 ''

注意：請謹慎決定是否實現對應方法，一旦你選擇在自己實現採集方法，此裝置標識的採集工作就由你全權接管了，SDK不會再試圖採集此裝置標識。SDK能採集到的裝置標識越少，對統計資料的準確性和穩定性負面影響越大

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.customSetMnc({
    mnc: ''
});

可用性

iOS系統

可提供的1.0.0及更高版本

自訂裝置ID

setCustomDeviceId

注意：

因此功能在未擷取umid時生效，本地如果已存在umid，設定後無效。如果本地已擷取到umid可以通過卸載重裝方式驗證此功能。

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.setCustomDeviceId({
    deviceId: 'xxxxxx'
});

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

擷取裝置ID

getUMIDString

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
var umidStr = qtAnalytics.getUMIDString();

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

登入

在統計使用者時以裝置為標準，如果需要統計應用自身的帳號，請使用此介面：

onProfileSignIn

注意：帳號ID設定後將被存入本機存放區，只有卸載App、清空應用資料或者調用下述的登入介面時，帳號ID才會失效，否則每一個事件都將攜帶帳號ID。

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.onProfileSignIn({userId:"custom_userId"});

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

登出

帳號登出時需調用此介面，調用之後不再發送帳號相關內容

onProfileSignOff

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.onProfileSignOff()

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

設定使用者屬性

在上報使用者屬性之前，需要先設定userId上報使用者帳號，否則QuickTracking流量分析對使用者屬性不會進行關聯計算。確認上報使用者的帳號ID後，上報使用者屬性介面為：

setUserProfile

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.setUserProfile({
    properties:{
        sex:"girl", //性別
        age:"8"//年齡
    }
});

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

註冊全域屬性

註冊全域屬性後，後續觸發的所有事件都將自動包含這些屬性；且這些屬性及屬性值存入緩衝，APP退出後清除。在分析資料時，可根據此屬性進行查看和篩選。

registerGlobalProperties

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
var param = {properties:{a:"1",b:"2"}};
qtAnalytics.registerGlobalProperties(param);//當前globalproperty為a:1和b:2

var param = {properties:{b:"3",c:"4"}};
qtAnalytics.registerGlobalProperties(param);//當前globalproperty為a:1、b:3和c:4

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

刪除一個全域屬性

unregisterGlobalProperty

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
var param = {propertyName:"lnch_Source"};
qtAnalytics.unregisterGlobalProperty(param);

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

根據Key擷取單個全域屬性

getGlobalProperty

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
var param = {propertyName:"lnch_Source"};
var gp = qtAnalytics.getGlobalProperty(param);

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

擷取所有全域屬性

getGlobalProperties

• 描述：返回字串中包含所有全域屬性及對應的屬性值，以 K-V索引值對的形式表示全域屬性-屬性值。多個索引值對間用逗號分割。資料外層是大括弧。如：{"id":"SA1375","userName":"Mike","account_type":"vip", "MemberLevel":"Level1"}

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
var allgp = qtAnalytics.getGlobalProperties();

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

清除所有的全域屬性

clearGlobalProperties

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.clearGlobalProperties();

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

頁面手動採集開始

開發人員如果希望對頁面路徑和頁面停留時間長度進行採集和統計。可以通過調用onPageStart/onPageEnd這組介面進行手動埋點。

注意：

• onPageStart 是SDK記錄頁面進入的資訊，onPageStart不會上報事件，只有調用onPageEnd的時候才會上報頁面瀏覽事件。

• onPageStart和onPageEnd必須成對調用，且傳值的pageName需要保持一致，如果沒有onPageEnd或者onPageEnd與onPageStart傳值的pageName不一致，則onPageStart記錄的資訊不會生效。

onPageStart

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.onPageStart({pageName:"MainScreen"});

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

頁面手動採集結束

onPageEnd

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.onPageEnd({pageName:"MainScreen"});

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

頁面屬性上傳

支援給當前頁面附加自訂屬性。

setPageProperty

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.onPageStart({pageName:"MainScreen"});
qtAnalytics.setPageProperty({
    pageName:"MainScreen",
    properties:{
        home_param_1:"value11" // 當前頁面相關屬性設定
    }
});

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

給下一個頁面附加自訂屬性

請注意：必須在下一個頁面onPageStart之前調用

setNextPageProperty

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.setNextPageProperty({
    properties: {
                nextPageProperty: "secondPageProperty"
            }
        });

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

事件埋點

自訂事件可以用於追蹤使用者行為，記錄行為發生的具體細節。

onEventObject

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.onEventObject({
    eventId:"play_music",
    pageName:"MainScreen",
    properties:{
        music_type:"popular", //自訂參數：音樂類型，值：流行
        singer:"JJ", //歌手：(林俊傑)JJ
        song_name:"A_Thousand_Years_Later", //歌名：一千年以後
        song_price:100 //價格：100元
    }
});

可用性

iOS系統，Android系統

可提供的1.0.0及更高版本

殺進程保護方法

如果開發人員調用kill或者exit之類的方法殺死進程，請務必在此之前調用onKillProcess，用來儲存統計資料。

onKillProcess

範例程式碼

var qtAnalytics = api.require('qtAnalytics');
qtAnalytics.onKillProcess();

可用性

Android系統

可提供的1.0.0及更高版本

注意事項

• 由於YonBuilder平台沒有透出openURL介面，因此iOS端暫時無法使用埋點驗證功能，您可以使用即時日誌驗證功能進行測試，擷取裝置ID的方式請參考：擷取裝置ID

• YonBuilder不支援全埋點功能

• YonBuilder不支援分享裂變功能