Countly基础知识

简介

Countly是一个创新的、实时的、开源的产品分析应用程序，为每个团队提供功能。它从手机、桌面应用程序(Mac OS X和Windows)、web应用程序和网站收集数据，并将这些信息可视化，以分析应用程序的使用情况和最终用户行为。Countly为关心用户数据隐私的公司提供产品分析服务。

Countly支持的操作系统

Countly正式提供与全球三大领先智能手机操作系统Android、iOS和Windows Phone的集成。此外，Countly还可以跟踪桌面应用程序和任何能够发送HTTP请求的设备，包括但不限于Windows和macOS。

企业微信20221229-161204.png

Countly对应用速度的影响

Countly对应用程序速度的影响可以忽略不计，它不会对应用程序加载时间和性能的任何方面产生不利影响。轻量级SDK异步工作，不会阻塞代码中的任何函数调用。iOS的分析显示，SDK在总CPU使用量中有2%的开销。使用Android分析器进行的测试证明，在典型的5分钟会话(发送5个事件和8个请求)使用场景中，Countly占用单个CPU时间的0.1%不到。对于更多的CPU内核，这个数字将低于0.1%。

企业微信20221228-150441.png

事件和会话数据如何发送到countly

当用户打开应用程序时，Countly SDK开始以应用程序定义的方式收集数据。对于移动sdk，每60秒通过HTTPS请求收集事件和会话，然后发送到Countly服务器，对于web sdk，每500毫秒发送一次。
请注意，一旦应用程序启动，就应该在仪表板上看到Session数据。但是，对于Events，需要等待，它每60秒发生一次心跳。如果在应用程序中记录了超过10个不同的事件，它甚至不会等待下一个心跳，而是立即发送它们。

集成

以下指导完成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将打印出关于其内部状态和遇到的问题的调试消息。这些消息可以在logcat中显示。
在配置类上调用setLoggingEnabled来启用日志记录:

CountlyConfig config = (new CountlyConfig(this, COUNTLY_APP_KEY, COUNTLY_SERVER_URL)); 
config.setLoggingEnabled(true);

Device ID

所有跟踪的信息都绑定到一个“设备ID”。设备ID是用户的唯一标识符。最简单的方法是让Countly SDK自行处理设备ID。使用以下调用，默认是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);

添加回调

在初始化之后，需要将以下调用添加到所有activity中:

override fun onStart() {
    super.onStart()
    if (!BuildConfig.DEBUG) {
        Countly.sharedInstance().onStart(this)
    }
}
 
 
override fun onStop() {
    super.onStop()
    if (!BuildConfig.DEBUG) {
        Countly.sharedInstance().onStop()
    }
}

如果你想跟踪手机配置发生改变（切换横竖屏、切换语言、切换输入法等），进行如下配置：

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()

自动崩溃处理

要启用自动崩溃报告，在配置对象上调用以下函数。在init之后，这将启用崩溃报告，它将自动捕获未捕获的Java异常。一旦应用再次启动并启动SDK，它们将被发送到仪表板。

config.enableCrashReporting();

自动崩溃报告分割

可以在崩溃报告中添加键/值段。例如，可以设置在应用程序中使用的特定库或框架的版本。就可以弄清楚特定库或框架与崩溃报告之间是否存在相关性。使用以下函数实现此目的:

config.setCustomCrashSegment(Map<String, String> segments)

处理异常

开发过程中可能会在应用程序运行时捕获异常或类似的错误。可以记录这些处理的异常，以监控它们如何以及何时发生，使用以下命令:

Countly.sharedInstance().crashes().recordHandledException(Exception exception);

如果已经处理了一个异常，并且它对应用程序是致命的，你可以使用这个调用:

Countly.sharedInstance().crashes().recordUnhandledException(Exception exception);

企业微信20221229-165254.png

Crash Breadcrumbs

在你的应用程序中，可以留下崩溃面包屑，这将描述在你的应用程序崩溃之前所采取的步骤。事故发生后，它们将与事故报告一起发送。
下面的命令添加了crash breadcrumb:

Countly.sharedInstance().crashes().addCrashBreadcrumb(String record)

Crash 筛选

在某些情况下，崩溃可能包含敏感信息。对于这种情况，有一个崩溃过滤选项。可以提供一个回调函数，每次记录崩溃时都会调用它。它获取崩溃的字符串值，该值将被发送到服务器，如果不应该将崩溃发送到服务器，则应该返回“true”:

config.setCrashFilterCallback(new CrashFilterCallback() {
    @Override
    public boolean filterCrash(String crash) {
        //returns true if the crash should be ignored
        return crash.contains("secret");
    }
})

记录所有线程

如果想在一个未捕获的异常或记录一个已处理的异常期间记录所有其他线程的状态，你可以在init期间调用:

config.setRecordAllThreadsWithCrash();

Events

任何类型的操作都可以发送给Countly，例如购买、更改设置、启用视图等等。通过这种方式，与默认情况下从Android SDK发送到Countly实例的信息相比，可以从应用程序中获得更多信息。通过SDK或API传递给Countly服务器的所有数据都应该是UTF-8格式。
在SDK中，所有与事件相关的功能都可以从仪表板上浏览:

Countly.sharedInstance().events()

为事件提供分段时，有效的数据类型是:"String"， "Integer"， "Double"和"Boolean"。所有其他类型将被忽略。

记录Events

企业微信20221229-114334.png

例如：购买事件发生的次数+总金额，分为国家和应用程序版本+这些事件的总持续时间。

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);

定时事件

可以通过定义开始和停止时刻来创建定时事件。

String eventName = "Some event";
//start some event
Countly.sharedInstance().events().startEvent(eventName);
//wait some time
 
//end the event
Countly.sharedInstance().events().endEvent(eventName);

可以在结束事件时提供附加信息。但是，在这种情况下，您必须提供分割、计数和和。默认值为“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

在前面的示例中，事件创建完成后，将记录事件创建时间。
在某些用例中，您可能希望自己缓存和存储的事件，然后用过去的时间戳将它们记录在SDK中。时间戳是以毫秒为单位存储的Unix时间戳。可以用:

Countly.sharedInstance().events().recordPastEvent(key, segmentation, count, sum, dur, timestamp)

企业微信20221229-145835.png

Sessions（会话）

手动会话

有时，手动控制会话比依赖SDK更好。可以在init期间使用:

config.enableManualSessionControl();

然后由实现者来调用:
开始会话
更新会话持续时间
结束会话(也更新持续时间)
这样做的适当调用是:

Countly.sharedInstance().sessions().beginSession(); 
Countly.sharedInstance().sessions().updateSession();
Countly.sharedInstance().sessions().endSession();

默认情况下，应该在开始会话后每60秒执行一些会话调用，以使会话在服务器端不关闭。如果你想要增加这个持续时间，你必须在你的服务器API配置中增加“最大会话持续时间”。

视图跟踪

在SDK中，所有与视图相关的功能都可以在界面中浏览:

Countly.sharedInstance().views()

自动视图跟踪

视图跟踪是一种向Countly仪表板报告每个屏幕视图的方法。为了启用自动视图跟踪，调用:

config.setViewTracking(true);

被跟踪的视图将使用包含其包名的完整活动名称。它看起来类似于“com.my.company.activityname”。

可以使用利用简单活动名称的短视图名称。这看起来像“activityname”。要使用此功能，请在调用init之前调用此函数:

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);

企业微信20221229-153228@2x.png

设备ID管理

第一次初始化SDK时，如果没有提供自定义设备ID，则会生成一个随机的设备ID。对于大多数用例来说，这就足够了，因为它为你的应用用户提供了一个随机的身份。
为了解决其他潜在的用例，我们提供了3种方法来处理您的设备id:

• 使用合并更改设备ID
• 在没有合并的情况下更改设备ID
• 使用临时ID

更改设备ID

合并更改设备ID

使用场景：eg：

• 应用程序对用户进行身份验证，希望在用户登录后将ID更改为后端中的ID，帮助在登录的设备上使用特定ID识别特定用户；
• 该用户使用不同的方式登录的情况(例如另一台平板电脑、另一部手机或web)在这种情况下，任何存储在Countly服务器数据库中与当前设备ID关联的数据将被转移(合并)到您在以下方法调用中指定的设备ID的用户配置文件中

Countly.sharedInstance().changeDeviceIdWithMerge("new device ID")

不合并更改设备ID

使用场景：eg:

• 想要跟踪另一个开始使用你的应用程序的单独用户的信息(更改应用程序帐户)，
• 应用程序进入一个状态，你不再能验证当前用户的身份(用户注销)。在这种情况下，可以将当前设备ID更改为新的设备ID，而无需合并它们的数据。

Countly.sharedInstance().changeDeviceIdWithoutMerge(DeviceId.Type.OPEN_UDID, null)

请注意，每次在没有合并的情况下更改deviceId时，它将被解释为一个新用户。因此，以一种糟糕的方式实现id管理可能会使用户数量大幅膨胀。因此，建议

• 在用户注销时保持相同的deviceId；
• 在特定设备上的用户注销时拥有一个预定的deviceId。
  第一种方法不会增加用户数量，但不适用于单设备、多用户的使用情况。第二种方法将为每个设备创建一个“多用户”id，可能会略微增加用户数量。

临时设备ID

在之前的ID管理方法中，数据仍然发送到您的服务器，但如果管理不当，会增加用户膨胀的风险。使用临时ID可以帮助缓解这类问题。
在app启动期间或init之后的任何时间，您都可以进入临时设备ID模式。所有请求都将存储在内部，在提供新的设备ID之前不会发送到服务器。在这种情况下，在这种临时ID模式下创建的所有事件都将与新的设备ID相关联并发送到服务器。
要在初始化期间启用该模式：

countlyConfig.enableTemporaryDeviceIdMode();

要在init后启用临时id：

Countly.sharedInstance().enableTemporaryIdMode();

要退出临时id模式，您可以调用“changeDeviceIdWithMerge”或“changeDeviceIdWithMerge”，或者使用开发人员提供的设备id初始化SDK。

检索当前设备ID

您可能希望看到Countly为特定设备分配了什么设备id，以及该id的来源是什么。为此，您可以使用以下调用。id类型为枚举，可取值为:"DEVELOPER_SUPPLIED"， "OPEN_UDID"， "ADVERTISING_ID"。

String usedId = Countly.sharedInstance().getDeviceID();
Type idType = Countly.sharedInstance().getDeviceIDType();