Countly基礎知識
簡介
Countly是一個創(chuàng)新的、實時的、開源的產(chǎn)品分析應用程序嘹朗，為每個團隊提供功能。它從手機诵肛、桌面應用程序(Mac OS X和Windows)屹培、web應用程序和網(wǎng)站收集數(shù)據(jù)，并將這些信息可視化怔檩，以分析應用程序的使用情況和最終用戶行為褪秀。Countly為關心用戶數(shù)據(jù)隱私的公司提供產(chǎn)品分析服務。
Countly支持的操作系統(tǒng)
Countly正式提供與全球三大領先智能手機操作系統(tǒng)Android珠洗、iOS和Windows Phone的集成溜歪。此外，Countly還可以跟蹤桌面應用程序和任何能夠發(fā)送HTTP請求的設備许蓖，包括但不限于Windows和macOS蝴猪。
Countly對應用速度的影響
Countly對應用程序速度的影響可以忽略不計，它不會對應用程序加載時間和性能的任何方面產(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
當用戶打開應用程序時芍锦，Countly SDK開始以應用程序定義的方式收集數(shù)據(jù)竹勉。對于移動sdk，每60秒通過HTTPS請求收集事件和會話娄琉，然后發(fā)送到Countly服務器次乓，對于web sdk，每500毫秒發(fā)送一次孽水。
請注意票腰，一旦應用程序啟動，就應該在儀表板上看到Session數(shù)據(jù)女气。但是杏慰，對于Events，需要等待炼鞠，它每60秒發(fā)生一次心跳逃默。如果在應用程序中記錄了超過10個不同的事件，它甚至不會等待下一個心跳簇搅，而是立即發(fā)送它們。
集成
以下指導完成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服務器url
SDK Logging
集成SDK時應該做的第一件事是啟用日志記錄意述。啟用了日志記錄提佣，SDK將打印出關于其內(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
所有跟蹤的信息都綁定到一個“設備ID”拌屏。設備ID是用戶的唯一標識符。最簡單的方法是讓Countly SDK自行處理設備ID术荤。使用以下調(diào)用倚喂，默認是OpenUDID。
CountlyConfig config = (new CountlyConfig(this, COUNTLY_APP_KEY, COUNTLY_SERVER_URL));
Countly.sharedInstance().init(config);
如果有設備ID瓣戚，可以自己指定設備ID(每個設備必須是唯一的)端圈。
CountlyConfig config = (new CountlyConfig(this, COUNTLY_APP_KEY, COUNTLY_SERVER_URL));
config.setDeviceId("YOUR_DEVICE_ID");
Countly.sharedInstance().init(config);
可以Android OS 提供的ID來生成設備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);
關于Android OS 提供的ID，請確保項目中包 Google Play services 4.0+舱权。另外矗晃，請注意，當 Google Play services在設備上不可用時刑巧，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
);
}
應用權限請求
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
Crash上報
Android的Countly SDK能夠收集崩潰報告拯辙，在SDK中，所有與崩潰相關的功能都可以在儀表板中瀏覽:
Countly.sharedInstance().crashes()
自動崩潰處理
要啟用自動崩潰報告颜价，在配置對象上調(diào)用以下函數(shù)涯保。在init之后，這將啟用崩潰報告周伦，它將自動捕獲未捕獲的Java異常夕春。一旦應用再次啟動并啟動SDK，它們將被發(fā)送到儀表板专挪。
config.enableCrashReporting();
自動崩潰報告分割
可以在崩潰報告中添加鍵/值段及志。例如，可以設置在應用程序中使用的特定庫或框架的版本寨腔。就可以弄清楚特定庫或框架與崩潰報告之間是否存在相關性速侈。使用以下函數(shù)實現(xiàn)此目的:
config.setCustomCrashSegment(Map<String, String> segments)
處理異常
開發(fā)過程中可能會在應用程序運行時捕獲異常或類似的錯誤迫卢∫邪幔可以記錄這些處理的異常，以監(jiān)控它們?nèi)绾我约昂螘r發(fā)生乾蛤，使用以下命令:
Countly.sharedInstance().crashes().recordHandledException(Exception exception);
如果已經(jīng)處理了一個異常每界，并且它對應用程序是致命的，你可以使用這個調(diào)用:
Countly.sharedInstance().crashes().recordUnhandledException(Exception exception);
Crash Breadcrumbs
在你的應用程序中幻捏，可以留下崩潰面包屑盆犁，這將描述在你的應用程序崩潰之前所采取的步驟。事故發(fā)生后篡九，它們將與事故報告一起發(fā)送谐岁。
下面的命令添加了crash breadcrumb:
Countly.sharedInstance().crashes().addCrashBreadcrumb(String record)
Crash 篩選
在某些情況下，崩潰可能包含敏感信息。對于這種情況伊佃，有一個崩潰過濾選項窜司。可以提供一個回調(diào)函數(shù)航揉，每次記錄崩潰時都會調(diào)用它塞祈。它獲取崩潰的字符串值，該值將被發(fā)送到服務器帅涂，如果不應該將崩潰發(fā)送到服務器议薪，則應該返回“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斯议，例如購買、更改設置醇锚、啟用視圖等等哼御。通過這種方式，與默認情況下從Android SDK發(fā)送到Countly實例的信息相比焊唬，可以從應用程序中獲得更多信息恋昼。通過SDK或API傳遞給Countly服務器的所有數(shù)據(jù)都應該是UTF-8格式。
在SDK中赶促，所有與事件相關的功能都可以從儀表板上瀏覽:
Countly.sharedInstance().events()
為事件提供分段時液肌，有效的數(shù)據(jù)類型是:"String"， "Integer"鸥滨， "Double"和"Boolean"矩屁。所有其他類型將被忽略。
記錄Events
例如：購買事件發(fā)生的次數(shù)+總金額爵赵，分為國家和應用程序版本+這些事件的總持續(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);
可以在結束事件時提供附加信息空幻。但是，在這種情況下容客，您必須提供分割秕铛、計數(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);
你可以取消開始計時事件，在它無關緊要的時候:
Countly.sharedInstance().events().cancelEvent(eventName);
過去的Events
在前面的示例中供置，事件創(chuàng)建完成后谨湘，將記錄事件創(chuàng)建時間。
在某些用例中，您可能希望自己緩存和存儲的事件紧阔，然后用過去的時間戳將它們記錄在SDK中坊罢。時間戳是以毫秒為單位存儲的Unix時間戳∩玫ⅲ可以用:
Countly.sharedInstance().events().recordPastEvent(key, segmentation, count, sum, dur, timestamp)
Sessions（會話）
手動會話
有時活孩，手動控制會話比依賴SDK更好」猿穑可以在init期間使用:
config.enableManualSessionControl();
然后由實現(xiàn)者來調(diào)用:
開始會話
更新會話持續(xù)時間
結束會話(也更新持續(xù)時間)
這樣做的適當調(diào)用是:
Countly.sharedInstance().sessions().beginSession();
Countly.sharedInstance().sessions().updateSession();
Countly.sharedInstance().sessions().endSession();
默認情況下憾儒，應該在開始會話后每60秒執(zhí)行一些會話調(diào)用，以使會話在服務器端不關閉乃沙。如果你想要增加這個持續(xù)時間起趾，你必須在你的服務器API配置中增加“最大會話持續(xù)時間”。
視圖跟蹤
在SDK中崔涂，所有與視圖相關的功能都可以在界面中瀏覽:
Countly.sharedInstance().views()
自動視圖跟蹤
視圖跟蹤是一種向Countly儀表板報告每個屏幕視圖的方法阳掐。為了啟用自動視圖跟蹤，調(diào)用:
config.setViewTracking(true);
被跟蹤的視圖將使用包含其包名的完整活動名稱冷蚂。它看起來類似于“com.my.company.activityname”缭保。
可以使用利用簡單活動名稱的短視圖名稱。這看起來像“activityname”蝙茶。要使用此功能艺骂，請在調(diào)用init之前調(diào)用此函數(shù):
config.setAutoTrackingUseShortName(true);
自動視圖分割
可以提供自定義分割，并將其設置為所有自動記錄的視圖:
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");
手動視圖分割
當手動跟蹤視圖時隆夯，你可以像這樣添加你的自定義分割:
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);
設備ID管理
第一次初始化SDK時钳恕，如果沒有提供自定義設備ID，則會生成一個隨機的設備ID蹄衷。對于大多數(shù)用例來說忧额，這就足夠了，因為它為你的應用用戶提供了一個隨機的身份愧口。
為了解決其他潛在的用例睦番，我們提供了3種方法來處理您的設備id:
- 使用合并更改設備ID
- 在沒有合并的情況下更改設備ID
- 使用臨時ID
更改設備ID
合并更改設備ID
使用場景：eg：
- 應用程序?qū)τ脩暨M行身份驗證，希望在用戶登錄后將ID更改為后端中的ID耍属，幫助在登錄的設備上使用特定ID識別特定用戶托嚣；
- 該用戶使用不同的方式登錄的情況(例如另一臺平板電腦、另一部手機或web)在這種情況下厚骗，任何存儲在Countly服務器數(shù)據(jù)庫中與當前設備ID關聯(lián)的數(shù)據(jù)將被轉(zhuǎn)移(合并)到您在以下方法調(diào)用中指定的設備ID的用戶配置文件中
Countly.sharedInstance().changeDeviceIdWithMerge("new device ID")
不合并更改設備ID
使用場景：eg:
- 想要跟蹤另一個開始使用你的應用程序的單獨用戶的信息(更改應用程序帳戶)示启，
- 應用程序進入一個狀態(tài)，你不再能驗證當前用戶的身份(用戶注銷)领舰。在這種情況下夫嗓，可以將當前設備ID更改為新的設備ID迟螺，而無需合并它們的數(shù)據(jù)。
Countly.sharedInstance().changeDeviceIdWithoutMerge(DeviceId.Type.OPEN_UDID, null)
請注意啤月，每次在沒有合并的情況下更改deviceId時煮仇，它將被解釋為一個新用戶。因此谎仲，以一種糟糕的方式實現(xiàn)id管理可能會使用戶數(shù)量大幅膨脹浙垫。因此，建議
- 在用戶注銷時保持相同的deviceId郑诺；
- 在特定設備上的用戶注銷時擁有一個預定的deviceId夹姥。
第一種方法不會增加用戶數(shù)量，但不適用于單設備辙诞、多用戶的使用情況辙售。第二種方法將為每個設備創(chuàng)建一個“多用戶”id，可能會略微增加用戶數(shù)量飞涂。
臨時設備ID
在之前的ID管理方法中旦部，數(shù)據(jù)仍然發(fā)送到您的服務器，但如果管理不當较店，會增加用戶膨脹的風險士八。使用臨時ID可以幫助緩解這類問題。
在app啟動期間或init之后的任何時間梁呈，您都可以進入臨時設備ID模式婚度。所有請求都將存儲在內(nèi)部，在提供新的設備ID之前不會發(fā)送到服務器官卡。在這種情況下蝗茁，在這種臨時ID模式下創(chuàng)建的所有事件都將與新的設備ID相關聯(lián)并發(fā)送到服務器。
要在初始化期間啟用該模式：
countlyConfig.enableTemporaryDeviceIdMode();
要在init后啟用臨時id：
Countly.sharedInstance().enableTemporaryIdMode();
要退出臨時id模式寻咒，您可以調(diào)用“changeDeviceIdWithMerge”或“changeDeviceIdWithMerge”哮翘，或者使用開發(fā)人員提供的設備id初始化SDK。
檢索當前設備ID
您可能希望看到Countly為特定設備分配了什么設備id毛秘，以及該id的來源是什么忍坷。為此，您可以使用以下調(diào)用熔脂。id類型為枚舉，可取值為:"DEVELOPER_SUPPLIED"柑肴， "OPEN_UDID"霞揉， "ADVERTISING_ID"。
String usedId = Countly.sharedInstance().getDeviceID();
Type idType = Countly.sharedInstance().getDeviceIDType();
