Countly基礎(chǔ)知識
簡介
Countly是一個創(chuàng)新的、實時的、開源的產(chǎn)品分析應(yīng)用程序，為每個團隊提供功能。它從手機、桌面應(yīng)用程序(Mac OS X和Windows)、web應(yīng)用程序和網(wǎng)站收集數(shù)據(jù)，并將這些信息可視化，以分析應(yīng)用程序的使用情況和最終用戶行為。Countly為關(guān)心用戶數(shù)據(jù)隱私的公司提供產(chǎn)品分析服務(wù)。
Countly支持的操作系統(tǒng)
Countly正式提供與全球三大領(lǐng)先智能手機操作系統(tǒng)Android、iOS和Windows Phone的集成。此外，Countly還可以跟蹤桌面應(yīng)用程序和任何能夠發(fā)送HTTP請求的設(shè)備，包括但不限于Windows和macOS。
Countly對應(yīng)用速度的影響
Countly對應(yīng)用程序速度的影響可以忽略不計，它不會對應(yīng)用程序加載時間和性能的任何方面產(chǎn)生不利影響。輕量級SDK異步工作，不會阻塞代碼中的任何函數(shù)調(diào)用。iOS的分析顯示，SDK在總CPU使用量中有2%的開銷。使用Android分析器進行的測試證明，在典型的5分鐘會話(發(fā)送5個事件和8個請求)使用場景中，Countly占用單個CPU時間的0.1%不到。對于更多的CPU內(nèi)核，這個數(shù)字將低于0.1%。
事件和會話數(shù)據(jù)如何發(fā)送到countly
當(dāng)用戶打開應(yīng)用程序時，Countly SDK開始以應(yīng)用程序定義的方式收集數(shù)據(jù)。對于移動sdk，每60秒通過HTTPS請求收集事件和會話，然后發(fā)送到Countly服務(wù)器，對于web sdk，每500毫秒發(fā)送一次。
請注意，一旦應(yīng)用程序啟動，就應(yīng)該在儀表板上看到Session數(shù)據(jù)。但是，對于Events，需要等待，它每60秒發(fā)生一次心跳。如果在應(yīng)用程序中記錄了超過10個不同的事件，它甚至不會等待下一個心跳，而是立即發(fā)送它們。
集成
以下指導(dǎo)完成Countly SDK的集成過程，它適用于22.06.X版本，Countly Android SDK要求Android最低版本為4.2.x (API等級17)。
向項目添加SDK
使用MavenCentral存儲庫下載SDK包。根目錄下的build.gradle配置如下:
buildscript {
repositories {
mavenCentral()
}
}
添加Countly SDK依賴項。app的build.gradle:
dependencies {
compile 'ly.count.android:sdk:22.06.0'
}
SDK集成
初始化:
在使用任何功能之前，必須初始化SDK。在Application中完成(首選)，或者在主活動onCreate方法中完成。
Countly.sharedInstance().init(new CountlyConfig(this, COUNTLY_APP_KEY, COUNTLY_SERVER_URL)); // COUNTLY_SERVER_URL:countly服務(wù)器url
SDK Logging
集成SDK時應(yīng)該做的第一件事是啟用日志記錄。啟用了日志記錄，SDK將打印出關(guān)于其內(nèi)部狀態(tài)和遇到的問題的調(diào)試消息。這些消息可以在logcat中顯示。
在配置類上調(diào)用setLoggingEnabled來啟用日志記錄:
CountlyConfig config = (new CountlyConfig(this, COUNTLY_APP_KEY, COUNTLY_SERVER_URL));
config.setLoggingEnabled(true);
Device ID
所有跟蹤的信息都綁定到一個“設(shè)備ID”。設(shè)備ID是用戶的唯一標(biāo)識符。最簡單的方法是讓Countly SDK自行處理設(shè)備ID。使用以下調(diào)用，默認是OpenUDID。
CountlyConfig config = (new CountlyConfig(this, COUNTLY_APP_KEY, COUNTLY_SERVER_URL));
Countly.sharedInstance().init(config);
如果有設(shè)備ID，可以自己指定設(shè)備ID(每個設(shè)備必須是唯一的)。
CountlyConfig config = (new CountlyConfig(this, COUNTLY_APP_KEY, COUNTLY_SERVER_URL));
config.setDeviceId("YOUR_DEVICE_ID");
Countly.sharedInstance().init(config);
可以Android OS 提供的ID來生成設(shè)備ID。
CountlyConfig config = (new CountlyConfig(appC, COUNTLY_APP_KEY, COUNTLY_SERVER_URL));
config.setIdMode(DeviceId.Type.ADVERTISING_ID); // id provided by the android OS
Countly.sharedInstance().init(config);
關(guān)于Android OS 提供的ID，請確保項目中包 Google Play services 4.0+。另外，請注意，當(dāng) Google Play services在設(shè)備上不可用時，Android OS 提供的ID會默認OpenUDID，以防它無法獲得ID。
也可以顯式地使用OpenUDID:
CountlyConfig config = (new CountlyConfig(appC, COUNTLY_APP_KEY, COUNTLY_SERVER_URL));
config.setIdMode(DeviceId.Type.OPEN_UDID);
Countly.sharedInstance().init(config);
添加回調(diào)
在初始化之后，需要將以下調(diào)用添加到所有activity中:
override fun onStart() {
super.onStart()
if (!BuildConfig.DEBUG) {
Countly.sharedInstance().onStart(this)
}
}
override fun onStop() {
super.onStop()
if (!BuildConfig.DEBUG) {
Countly.sharedInstance().onStop()
}
}
如果你想跟蹤手機配置發(fā)生改變（切換橫豎屏、切換語言、切換輸入法等），進行如下配置：
override fun onConfigurationChanged(newConfig: Configuration) {
super.onConfigurationChanged(newConfig)
Countly.sharedInstance().onConfigurationChanged(
newConfig
);
}
應(yīng)用權(quán)限請求
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
Crash上報
Android的Countly SDK能夠收集崩潰報告，在SDK中，所有與崩潰相關(guān)的功能都可以在儀表板中瀏覽:
Countly.sharedInstance().crashes()
自動崩潰處理
要啟用自動崩潰報告，在配置對象上調(diào)用以下函數(shù)。在init之后，這將啟用崩潰報告，它將自動捕獲未捕獲的Java異常。一旦應(yīng)用再次啟動并啟動SDK，它們將被發(fā)送到儀表板。
config.enableCrashReporting();
自動崩潰報告分割
可以在崩潰報告中添加鍵/值段。例如，可以設(shè)置在應(yīng)用程序中使用的特定庫或框架的版本。就可以弄清楚特定庫或框架與崩潰報告之間是否存在相關(guān)性。使用以下函數(shù)實現(xiàn)此目的:
config.setCustomCrashSegment(Map<String, String> segments)
處理異常
開發(fā)過程中可能會在應(yīng)用程序運行時捕獲異?；蝾愃频腻e誤。可以記錄這些處理的異常，以監(jiān)控它們?nèi)绾我约昂螘r發(fā)生，使用以下命令:
Countly.sharedInstance().crashes().recordHandledException(Exception exception);
如果已經(jīng)處理了一個異常，并且它對應(yīng)用程序是致命的，你可以使用這個調(diào)用:
Countly.sharedInstance().crashes().recordUnhandledException(Exception exception);
Crash Breadcrumbs
在你的應(yīng)用程序中，可以留下崩潰面包屑，這將描述在你的應(yīng)用程序崩潰之前所采取的步驟。事故發(fā)生后，它們將與事故報告一起發(fā)送。
下面的命令添加了crash breadcrumb:
Countly.sharedInstance().crashes().addCrashBreadcrumb(String record)
Crash 篩選
在某些情況下，崩潰可能包含敏感信息。對于這種情況，有一個崩潰過濾選項。可以提供一個回調(diào)函數(shù)，每次記錄崩潰時都會調(diào)用它。它獲取崩潰的字符串值，該值將被發(fā)送到服務(wù)器，如果不應(yīng)該將崩潰發(fā)送到服務(wù)器，則應(yīng)該返回“true”:
config.setCrashFilterCallback(new CrashFilterCallback() {
@Override
public boolean filterCrash(String crash) {
//returns true if the crash should be ignored
return crash.contains("secret");
}
})
記錄所有線程
如果想在一個未捕獲的異?；蛴涗浺粋€已處理的異常期間記錄所有其他線程的狀態(tài)，你可以在init期間調(diào)用:
config.setRecordAllThreadsWithCrash();
Events
任何類型的操作都可以發(fā)送給Countly，例如購買、更改設(shè)置、啟用視圖等等。通過這種方式，與默認情況下從Android SDK發(fā)送到Countly實例的信息相比，可以從應(yīng)用程序中獲得更多信息。通過SDK或API傳遞給Countly服務(wù)器的所有數(shù)據(jù)都應(yīng)該是UTF-8格式。
在SDK中，所有與事件相關(guān)的功能都可以從儀表板上瀏覽:
Countly.sharedInstance().events()
為事件提供分段時，有效的數(shù)據(jù)類型是:"String"， "Integer"， "Double"和"Boolean"。所有其他類型將被忽略。
記錄Events
例如：購買事件發(fā)生的次數(shù)+總金額，分為國家和應(yīng)用程序版本+這些事件的總持續(xù)時間。
HashMap<String, String> segmentation = new HashMap<String, Object>();
segmentation.put("country", "Germany");
segmentation.put("app_version", "1.0");
Countly.sharedInstance().events().recordEvent("purchase", segmentation, 1, 0.99, 60);
定時事件
可以通過定義開始和停止時刻來創(chuàng)建定時事件。
String eventName = "Some event";
//start some event
Countly.sharedInstance().events().startEvent(eventName);
//wait some time
//end the event
Countly.sharedInstance().events().endEvent(eventName);
可以在結(jié)束事件時提供附加信息。但是，在這種情況下，您必須提供分割、計數(shù)和和。默認值為“null”、1和0。
String eventName = "Some event";
//start some event
Countly.sharedInstance().events().startEvent(eventName);
//wait some time
Map<String, String> segmentation = new HashMap<>();
segmentation.put("wall", "orange");
//end the event while also providing segmentation information, count and sum
Countly.sharedInstance().events().endEvent(eventName, segmentation, 4, 34);
你可以取消開始計時事件，在它無關(guān)緊要的時候:
Countly.sharedInstance().events().cancelEvent(eventName);
過去的Events
在前面的示例中，事件創(chuàng)建完成后，將記錄事件創(chuàng)建時間。
在某些用例中，您可能希望自己緩存和存儲的事件，然后用過去的時間戳將它們記錄在SDK中。時間戳是以毫秒為單位存儲的Unix時間戳?？梢杂?
Countly.sharedInstance().events().recordPastEvent(key, segmentation, count, sum, dur, timestamp)
Sessions（會話）
手動會話
有時，手動控制會話比依賴SDK更好?？梢栽趇nit期間使用:
config.enableManualSessionControl();
然后由實現(xiàn)者來調(diào)用:
開始會話
更新會話持續(xù)時間
結(jié)束會話(也更新持續(xù)時間)
這樣做的適當(dāng)調(diào)用是:
Countly.sharedInstance().sessions().beginSession();
Countly.sharedInstance().sessions().updateSession();
Countly.sharedInstance().sessions().endSession();
默認情況下，應(yīng)該在開始會話后每60秒執(zhí)行一些會話調(diào)用，以使會話在服務(wù)器端不關(guān)閉。如果你想要增加這個持續(xù)時間，你必須在你的服務(wù)器API配置中增加“最大會話持續(xù)時間”。
視圖跟蹤
在SDK中，所有與視圖相關(guān)的功能都可以在界面中瀏覽:
Countly.sharedInstance().views()
自動視圖跟蹤
視圖跟蹤是一種向Countly儀表板報告每個屏幕視圖的方法。為了啟用自動視圖跟蹤，調(diào)用:
config.setViewTracking(true);
被跟蹤的視圖將使用包含其包名的完整活動名稱。它看起來類似于“com.my.company.activityname”。
可以使用利用簡單活動名稱的短視圖名稱。這看起來像“activityname”。要使用此功能，請在調(diào)用init之前調(diào)用此函數(shù):
config.setAutoTrackingUseShortName(true);
自動視圖分割
可以提供自定義分割，并將其設(shè)置為所有自動記錄的視圖:
Map<String, Object> automaticViewSegmentation = new HashMap<>();
automaticViewSegmentation.put("One", 2);
automaticViewSegmentation.put("Three", 4.44d);
automaticViewSegmentation.put("Five", "Six");
config.setAutomaticViewSegmentation(automaticViewSegmentation);
手動視圖記錄
也可以使用以下代碼片段跟蹤自定義視圖:
Countly.sharedInstance().views().recordView("View name");
手動視圖分割
當(dāng)手動跟蹤視圖時，你可以像這樣添加你的自定義分割:
Map<String, Object> viewSegmentation = new HashMap<>();
viewSegmentation.put("Cats", 123);
viewSegmentation.put("Moons", 9.98d);
viewSegmentation.put("Moose", "Deer");
Countly.sharedInstance().views().recordView("Better view", viewSegmentation);
設(shè)備ID管理
第一次初始化SDK時，如果沒有提供自定義設(shè)備ID，則會生成一個隨機的設(shè)備ID。對于大多數(shù)用例來說，這就足夠了，因為它為你的應(yīng)用用戶提供了一個隨機的身份。
為了解決其他潛在的用例，我們提供了3種方法來處理您的設(shè)備id:
- 使用合并更改設(shè)備ID
- 在沒有合并的情況下更改設(shè)備ID
- 使用臨時ID
更改設(shè)備ID
合并更改設(shè)備ID
使用場景：eg：
- 應(yīng)用程序?qū)τ脩暨M行身份驗證，希望在用戶登錄后將ID更改為后端中的ID，幫助在登錄的設(shè)備上使用特定ID識別特定用戶；
- 該用戶使用不同的方式登錄的情況(例如另一臺平板電腦、另一部手機或web)在這種情況下，任何存儲在Countly服務(wù)器數(shù)據(jù)庫中與當(dāng)前設(shè)備ID關(guān)聯(lián)的數(shù)據(jù)將被轉(zhuǎn)移(合并)到您在以下方法調(diào)用中指定的設(shè)備ID的用戶配置文件中
Countly.sharedInstance().changeDeviceIdWithMerge("new device ID")
不合并更改設(shè)備ID
使用場景：eg:
- 想要跟蹤另一個開始使用你的應(yīng)用程序的單獨用戶的信息(更改應(yīng)用程序帳戶)，
- 應(yīng)用程序進入一個狀態(tài)，你不再能驗證當(dāng)前用戶的身份(用戶注銷)。在這種情況下，可以將當(dāng)前設(shè)備ID更改為新的設(shè)備ID，而無需合并它們的數(shù)據(jù)。
Countly.sharedInstance().changeDeviceIdWithoutMerge(DeviceId.Type.OPEN_UDID, null)
請注意，每次在沒有合并的情況下更改deviceId時，它將被解釋為一個新用戶。因此，以一種糟糕的方式實現(xiàn)id管理可能會使用戶數(shù)量大幅膨脹。因此，建議
- 在用戶注銷時保持相同的deviceId；
- 在特定設(shè)備上的用戶注銷時擁有一個預(yù)定的deviceId。
第一種方法不會增加用戶數(shù)量，但不適用于單設(shè)備、多用戶的使用情況。第二種方法將為每個設(shè)備創(chuàng)建一個“多用戶”id，可能會略微增加用戶數(shù)量。
臨時設(shè)備ID
在之前的ID管理方法中，數(shù)據(jù)仍然發(fā)送到您的服務(wù)器，但如果管理不當(dāng)，會增加用戶膨脹的風(fēng)險。使用臨時ID可以幫助緩解這類問題。
在app啟動期間或init之后的任何時間，您都可以進入臨時設(shè)備ID模式。所有請求都將存儲在內(nèi)部，在提供新的設(shè)備ID之前不會發(fā)送到服務(wù)器。在這種情況下，在這種臨時ID模式下創(chuàng)建的所有事件都將與新的設(shè)備ID相關(guān)聯(lián)并發(fā)送到服務(wù)器。
要在初始化期間啟用該模式：
countlyConfig.enableTemporaryDeviceIdMode();
要在init后啟用臨時id：
Countly.sharedInstance().enableTemporaryIdMode();
要退出臨時id模式，您可以調(diào)用“changeDeviceIdWithMerge”或“changeDeviceIdWithMerge”，或者使用開發(fā)人員提供的設(shè)備id初始化SDK。
檢索當(dāng)前設(shè)備ID
您可能希望看到Countly為特定設(shè)備分配了什么設(shè)備id，以及該id的來源是什么。為此，您可以使用以下調(diào)用。id類型為枚舉，可取值為:"DEVELOPER_SUPPLIED"， "OPEN_UDID"， "ADVERTISING_ID"。
String usedId = Countly.sharedInstance().getDeviceID();
Type idType = Countly.sharedInstance().getDeviceIDType();
