C# SDK 使用說明

在使用前，請先閱讀數據模型的介绍。
C# SDK 主要適用於伺服器 .NET 框架之上的應用，目前支援 .Net Core 2.0+ 和 .Net Framework 4.6.1+；同時支援透過 NuGet 方式整合我們的 SDK。

1. 整合神策分析 SDK

在伺服器 .NET 應用中整合神策分析 SDK，使用神策分析採集並分析用戶行為。
SDK 的工程原始碼可以從 GitHub 下載，並選用下面的一種方法進行整合：

(推薦）透過 NuGet 方式直接引入我們的 SDK: https://www.nuget.org/packages/SensorsData.Analytics/
對 SDK 原始碼編譯後從 Release 目錄下取得 dll 文件用於整合；
將 SDK 專案其作為模組增加進需要整合的專案中使用。

2. 初始化神策分析 SDK

2.1 取得設定資訊

首先從神策分析的主頁中，取得數據接收的 URL 和 Token（Cloud 版）。

如果使用神策分析 Cloud 服務，需取得的設定資訊為:

數據接收網址，建議使用不帶埠號的: http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}
數據接收網址，帶埠號的: http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}

如果用戶使用單機版私有部署的神策分析，預設的設定資訊為：

數據接收網址: http://{$host_name}:8106/sa?project={$project_name}（注：神策分析 1.7 及之前的版本，單機版私有部署預設埠號為 8006）

如果用戶使用叢集版私有部署的神策分析，預設的設定資訊為：

數據接收網址: http://{$host_name}:8106/sa?project={$project_name}

其中 {$host_name} 可以是叢集中任意一台電腦。

如果私有部署的過程中修改了 Nginx 的預設設定，或透過 CDN 等連接神策分析，則請諮詢相關人員取得設定資訊。

2.2 在程式中初始化 SDK

在程式啟動時（如 static void Main(string[] args) 方法中），呼叫建構函式 new SensorsAnalytics(consumer) 初始化 SDK 執行個體。

// 使用 LoggingConsumer 初始化 SensorsAnalytics
IConsumer consumer = new LoggingConsumer("D:/test/");
SensorsAnalytics sa = new SensorsAnalytics(consumer);

// 用戶的 Distinct Id
String distinctId = "ABCDEF123456789";

// 記錄用戶登入事件
sa.Track(distinctId, "UserLogin");

// 使用神策分析記錄用戶行為數據
// ...

// 程式结束前，停止神策分析 SDK 所有服務
sa.Shutdown();

C#

程式结束前需要使用 shutdown() 介面表示结束，該介面可能需要等待若干秒，直到本地快取的數據都已傳送到神策分析。

至此，我們已經可以正常使用神策分析 SDK 採集用戶數據了。在開發多執行緒程式時，開發者可以在執行緒間重複使用神策分析執行個體用於記錄數據。

3.追蹤事件

第一次接入神策分析時，建議先追蹤 3~5 個關鍵的事件，只需要幾行程式碼，便能體驗神策分析的分析功能。例如：

圖片社交產品，可以追蹤用戶瀏覽圖片和評論事件
電商產品，可以追蹤用戶註冊、瀏覽商品和下訂單等事件

Sensors Analytics SDK 初始化成功後，可以透過 track() 記錄事件，必須包含用戶ID（distinctId ）和事件名（eventName）這兩個參數，同時可以傳入一個 Dictionary<String, Object> 對象，為事件增加自定義事件屬性，在自定義屬性中需要包含 $is_login_id 屬性來說明 distinct_id 是否為登入ID。以電商產品為例，可以這樣追蹤一次購物行為：

// 用戶的 Distinct Id
String distinctId = "ABCDEF123456789";

// 用戶瀏覽商品
Dictionary<string, Object> properties = new Dictionary<string, object>();

   // '$time' 屬性是系統預設屬性，表示事件發生的時間，如果不填入該屬性，則預設使用系統當前時間
   properties.Add("$time", new Date());
   // '$ip' 屬性是系統預設屬性，如果伺服器中能取得用戶 IP 網址，並填入該屬性，神策分析會自動根據 IP 網址解析用戶的省份、城市資訊
   properties.Add("$ip", "123.123.123.123");
   // $is_login_id 屬性判斷 distinct_id 是否為登入 ID，如果是則設定為 true，否則為 false，預設為 false
   properties.Add("$is_login_id", true);
   // 商品 ID
   properties.Add("ProductId", "123456");
   // 商品類別
   properties.Add("ProductCatalog", "Laptop Computer");
   // 是否加入收藏夾，Boolean 型別的屬性
   properties.Add("isAddedToFav", true);

   // 記錄用戶瀏覽商品事件
   sa.Track(distinctId, "ViewProduct", properties);
}

C#

3.1 事件屬性

如前文中的範例，追蹤的事件可以設定自定義的事件屬性，例如瀏覽商品事件中，將商品 ID、商品分類等資訊作為事件屬性。在後續的分析工作中，事件屬性可以作為統計過濾條件使用，也可以作為維度進行多維分析。對於事件屬性，神策分析有一些限制:

事件屬性是一个 Dictionary<String, Object> 物件
Dictionary<String, Object> 中每個元素描述一個屬性，Key 為屬性名稱，必需是 String 型別
Dictionary<String, Object> 中，每個元素的 Value 是屬性的值，支援 String、Number、List<String> 和 Date

對於神策分析中事件屬性的更多限制，請參考數據格式。在開發多執行緒程式時，開發者不能在執行緒間重複使用傳入的屬性對象。

3.1.1 系統預設屬性

如前文中範例，事件屬性中以 $ 開頭的屬性為系統預設屬性，在自定義事件屬性中填入對應 $ 開頭的屬性值可以覆蓋這些預設屬性：

$ip - 填入該屬性，神策分析會自動根據 IP 網址解析用戶的省份、城市資訊，該屬性值為 String 型別；
$time - 填入該屬性，神策分析將事件時間設定為屬性值的時間，該屬性值必須為 Date 型別。請注意，神策分析預設會過濾忽略 365 天前或 3 天後的數據，如需修改請聯繫我們。

關於其他更多預設屬性，請參考數據格式中 預設屬性 一節。

3.1.2 事件公共屬性

特別地，如果某個事件的屬性，在所有事件中都會出現，可以透過 RegisterSuperPropperties() 將該屬性設定為事件公共屬性。例如電商產品中的用戶等級，常作為事件的公共屬性，設定方法如下:

Dictionary<string, Object> properties = new Dictionary<string, object>();
// 伺服器應用版本
properties.Add("ServerVersion", "1.2");
// 伺服器機房網址
properties.Add("Location", "BeiJing");
// 設定事件公共屬性
sa.RegisterSuperPropperties(properties);

C#

成功設定事件公共屬性後，再透過 track()追蹤事件時，事件公共屬性會被增加進每個事件中，例如：

Dictionary<string, Object> properties = new Dictionary<string, object>();
// 登入用戶端 IP 網址
properties.Add("$ip", "123.123.123.123");
//追蹤用戶登入事件
sa.Track("ABCDEF123456789", "UserLogin", properties);

C#

在設定事件公共屬性後，實際傳送的事件中會被加入 ServerVersion 和 Location 屬性，等價於

Dictionary<string, Object> properties = new Dictionary<string, object>();
// 事件公共屬性
properties.Add("ServerVersion", "1.2");
properties.Add("Location", "BeiJing");
// 登入用戶端 IP 網址
properties.Add("$ip", "123.123.123.123");
//追蹤用戶登入事件
sa.Track("ABCDEF123456789","UserLogin", properties);

C#

使用 ClearSuperProperties() 會刪除所有已設定的事件公共屬性。

當事件公共屬性和事件屬性的 Key 衝突時，事件屬性優先級最高，它會覆蓋事件公共屬性。

4. 用戶識別

在伺服器端應用中，神策分析也要求為每個事件設定用戶的 Distinct Id，這有助於神策分析提供更準確的留存率等數據。

對於註冊用戶，推薦使用系統中的用戶 ID 作為 Distinct Id，不建議使用用戶名、Email、手機號碼等可以被修改的資訊；

對於未註冊的匿名用戶：

1. 如果前端網頁中使用了 JavaScript SDK，您可以在 Cookie 裡面找到 key 為 sensorsdata2015jssdkcross 的 value 值然後進行 decodeURIComponent 解析，最後透過 JSON.parse 方法得到一個物件，物件裡面的 distinct_id 即為用戶所需要的。
2. 如果 APP 中嵌入了 iOS SDK 或 Android SDK，您需要自己將匿名 ID 傳到伺服器器端應用，然後取得這個匿名 ID 作為用戶標識 Distinct Id。
3. 如果您没有使用前端 SDK（JS SDK / iOS SDK / Android SDK），則伺服器也要產生一個隨機 ID 作為用戶標識 Distinct Id。每一個隨機 ID 被認為一個獨立的用戶。

所有的 track 和 profile 系列方法都必須同時指定用戶 ID及用戶 ID 是否為登入 ID這兩個參數，以便明確告知神策分析用戶 ID 的類型。

4.1 用戶註冊/登入

當同一個用戶的 Distinct Id 發生變化時（一般情況為匿名用戶註冊行為），可以透過 trackSignUp() 將舊的 Distinct Id 和新的 Distinct Id 關聯，以確保用戶分析的準確性。例如：

 // 匿名 ID 由前端傳過来
String anonymousId = "9771C579-71F0-4650-8EE8-8999FA717761";

// 註冊用戶的真實 ID
String registerId = "0012345678";
// 用戶註冊/登入時，將用戶註冊 ID 與 匿名 ID 關聯
sa.TrackSignUp(registerId, anonymousId);

C#

注意，對同一個用戶，TrackSignUp() 一般情況下建議只呼叫一次（通常在用戶注册時呼叫），用戶登入前後的行為的關聯建議在業務端實現。在神策分析 1.13 版本之前，多次呼叫 TrackSignUp()時，只有第一次關聯行為是有效的。神策分析 1.13 版本之後提供了多裝置 id 關聯的方法。更詳細的說明請參考如何準確的標示用戶，並在必要時聯繫我們的技術支援人員。

5. 設定用戶屬性

為了更準確地提供針對人群的分析服務，神策分析 SDK 可以設定用戶屬性，如年齡、性別等。用戶可以在留存分析、分佈分析等功能中，使用用戶屬性作為過濾條件或以用戶屬性作為維度進行多維分析。

使用 ProfileSet() 設定用戶屬性:

String distinctId = "ABCDEF123456789";

Dictionary<string, Object> properties = new Dictionary<string, object>();
// 設定用戶等級屬性（Level）為 VIP
properties.Add("UserLv", "Elite VIP");
// $is_login_id 屬性判斷 distinct_id 是否為登入 ID，如果是則設定為 true，否則為 false，預設為 false
properties.Add("$is_login_id", true);

sa.ProfileSet(distinctId, properties);

C#

對於不再需要的用戶屬性，可以透過 ProfileUnset() 介面將屬性刪除。

用戶屬性中，屬性名稱與屬性值的限制條件與事件屬性相同，詳細說明請參考數據格式。

5.1 記錄初次設定的屬性

對於只在首次設定時有效的屬性，我們可以使用 ProfileSetOnce() 記錄这些屬性。與 ProfileSet() 介面不同的是，如果被設定的用戶屬性已存在，則這條記錄會被忽略而不會覆蓋已有數據，如果屬性不存在則會自動建立。因此，profileSetOnce() 比較適用於為用戶設定首次啟用時間、首次註冊時間等屬性。例如：

String distinctId = "ABCDEF123456789";

Dictionary<string, Object> properties = new Dictionary<string, object>();
// 設定用戶管道屬性（AdSource）為 "App Store"
properties.Add("AdSource", "App Store");
// $is_login_id 屬性判斷 distinct_id 是否為登入 ID，如果是則設定為 true，否則為 false，預設為 false
properties.Add("$is_login_id", true);

sa.ProfileSetOnce(distinctId,properties);

// 再次設定用戶管道屬性（AdSource），設定無效，屬性 "AdSource" 的值仍為 "App Store"
properties.Add("AdSource", "Search Engine");

sa.ProfileSetOnce(distinctId, properties);

C#

5.2 數值類型的屬性

對於數值型的用戶屬性，可以使用 ProfileIncrement() 對屬性值進行累加。常用於記錄用戶付費次數、付費額度、積分等屬性。例如：

String distinctId = "ABCDEF123456789";

Dictionary<string, Object> properties = new Dictionary<string, object>();
// 設定用戶遊戲次數屬性（GamePlayed），將次數累加1次
properties.Add("GamePlayed", 1);
// $is_login_id 屬性判斷 distinct_id 是否為登入 ID，如果是則設定為 true，否則為 false，預設為 false
properties.Add("$is_login_id", true);

sa.ProfileIncrement(distinctId,properties );

C#

5.3 列表類型的屬性

對於用戶喜愛的電影、用戶評價過的餐廳等屬性，可以記錄列表型屬性。需要注意的是，列表型屬性中的元素必須為 String 類型，且元素的值會自動去重。關於列表型別限制請見數據格式 7.3 屬性長度限制。

String distinctId = "ABCDEF123456789";

// 電影列表
List<String> movies = new List<String>();
movies.Add("Sicario");
movies.Add("Love Letter");

// 遊戲列表
List<String> games = new List<String>();
games.Add("Call of Duty");
games.Add("Halo");

// 用戶屬性
Dictionary<string, Object> properties = new Dictionary<string, object>();
properties.Add("movies", movies);
properties.Add("games", games);

// 傳入properties，設定用戶喜歡的電影屬性（movies）和喜歡的遊戲數性（games）
// 設定成功後，"movies" 屬性值為 ["Sicario", "Love Letter"]；"games" 屬性值為 ["Call of Duty", "Halo"]
sa.ProfileAppend(distinctId, properties);

// 此方法還有一個重載方法，方便處理只有一個值的情況
// 傳入屬性名稱和需要插入屬性的值，設定用戶喜歡的電影屬性（movies）
// 設定成功後 "movies" 屬性值為 ["Dead Poets Society"]
sa.ProfileAppend(distinctId, "movies", "Dead Poets Society");

C#

6. 物品元數據上報

在神策推薦專案中，客戶需要將物品元數據上報，以開展後續推薦業務的開發與維護。神策分析 SDK 提供了設定與刪除物品元數據的方法。

item_id（物品 ID ）與 item_type （物品所屬型別）共同組成了一個物品的唯一標識。所有的 item 系列方法都必須同時指定物品 ID 及物品所屬型別這兩個參數，來完成對物品的操作。

6.1. 設定物品

直接設定一個物品，如果已存在則覆蓋。除物品 ID 與物品所屬類型外，其他物品屬性需在 properties 中定義。

物品屬性中，屬性名稱與屬性值的限制條件與事件屬性相同，詳細說明請參考數據格式。

public void ItemSet(String itemType, String itemId, Dictionary<String, Object> properties)

// 例如
Dictionary<string, Object> properties = new Dictionary<string, object>();
properties.put("name", "C++ Primer");
properties.put("price", 31.54);
sensorsAnalytics.ItemSet("book", "0321714113", properties);

C#

6.2. 刪除一個物品

如果物品不被推薦而需要下線，刪除該物品即可，如不存在則忽略。

除物品 ID 與物品所屬型別外，不解析其他物品屬性。

public void ItemDelete(String itemType, String itemId);

// 例如
sensorsAnalytics.itemDelete("book", "0321714113");

C#

7. 設定神策分析 SDK

以下內容說明如何更精細地控制神策分析 SDK 的行為。

7.1. 數據採集

C# SDK 主要由以下兩個元件構成:

SensorsAnalytics: 用於傳送數據的介面物件，建構函式需要傳入一個 Consumer 執行個體。
Consumer: Consumer 會進行實際的數據傳送

為了讓開發者更靈活的接入數據，神策分析 SDK 實作了以下 Consumer:

LoggingConsumer: 用於將數據輸出到指定目錄，在生產環境中需使用 LoggingConsumer 並配合 LogAgent 工具上報數據，該工具能確保匯入的數據不重複、不遺漏。

// 使用 LoggingConsumer 初始化 SensorsAnalytics
// "D:/test/" 是文件路徑，需要提前建立；之後會自動在此目錄下產生格式為 "yyyyMMdd.txt" 的 log 文件
IConsumer consumer = new LoggingConsumer("D:/test/");
SensorsAnalytics sa = new SensorsAnalytics(consumer);

// 使用神策分析 記錄用戶行為數據
// ...

// 程式結束前，停止神策分析 SDK 所有服務
sa.Shutdown();

C#