Golang SDK 使用ガイド

このガイドでは、Golang SDK を使用してプロジェクトにアクセスする方法について説明します。にアクセスしてGitHub (opens new window)Golang SDK のソースコードを入手できます。

最新バージョンバージョン:1.5.0

更新時間は: 2021-11-02

まず、SDK の統合と初期化

1.1 統合 SDK

次のコマンドを実行して、最新バージョンの Golang SDK を入手します。

# 获取 SDK
go get github.com/ThinkingDataAnalytics/go-sdk/thinkingdata

# 更新 SDK
go get -u github.com/ThinkingDataAnalytics/go-sdk/thinkingdata

モジュールモード:

//在代码文件开头引入thinkingdata
import	"github.com/ThinkingDataAnalytics/go-sdk/thinkingdata"

# 拉取最新SDK模块
go mod tidy

1.2 SDK の初期化

まずコードブックの冒頭に thinkingdata を導入導入:

// import thinkingdata sdk
import	"github.com/ThinkingDataAnalytics/go-sdk/thinkingdata"

SDK を使用してデータをアップロードするには、まず TDAnalytics インスタンスを作成作成インスタンスを作成インスタンスには、Consumer インターフェイスを実装したConsumerインターフェイスを実装した構造体が必要ですConsumerの定義は次のとおりです。

// Consumer 为数据实现 IO 操作（写入磁盘或者发送到接收端）
type Consumer interface {
	Add(d Data) error
	Flush() error
	Close() error
}

thinkingdataパッケージは、Consumerの 3 つの実装を提供します

(1)LogConsumer:データをリアルタイムでローカルテキストに書き込み、テキストを日/時間で区切り、LogBus と組み合わせてデータをアップロード

// 创建按天切分的 LogConsumer, 不设置单个日志上限
consumer, err := thinkingdata.NewLogConsumer("/path/to/data", thinkingdata.ROTATE_DAILY)

// 创建按小时切分的 LogConsumer, 不设置单个日志上限
consumer, err := thinkingdata.NewLogConsumer("/path/to/data", thinkingdata.ROTATE_HOURLY)

// 创建按天切分的 LogConsumer，并设置单个日志文件上限为 10 G
consumer, err := thinkingdata.NewLogConsumerWithFileSize("/path/to/data", thinkingdata.ROTATE_DAILY, 10 * 1024)

// 指定生成的文件前缀
config := LogConfig{
		Directory:  "/path/to/data",
		RotateMode: thinkingdata.ROTATE_DAILY,
		FileNamePrefix: "prefix",
	}
consumer, err := thinkingdata.NewLogConsumerWithConfig(config)

受信パラメータは、ローカルフォルダアドレスを書き込みます。LogBus の受信フォルダアドレスをここに設定するだけで、LogBus を使用してデータの受信アップロードを実行できます

(2)BatchConsumer:一括でリアルタイムに TA サーバにデータを転送するため、転送ツールを組み合わせる必要が**、長時間ネットワークが中断した場合、データが失われるリスクが**

// 创建 BatchConsumer, 指定接收端地址、APP ID
consumer, err := thinkingdata.NewBatchConsumer("SERVER_URL", "APP_ID")

// 创建 BatchConsumer, 设置数据不压缩，默认gzip压缩，可在内网传输
consumer, err := thinkingdata.NewBatchConsumerWithCompress("SERVER_URL", "APP_ID",false)

SERVER_URLは転送データの URL、APP_IDはプロジェクトの APP ID

クラウドサービスを使用している場合は、次の URL を入力してください

http://ta-receiver.thinkingdata.io

民営化された展開のバージョンを使用している場合は、次の URL を入力してください

http://数据采集地址

注意:バージョン 1.1.0 以前に次の URL を入力してください:

http://ta-receiver.thinkingdata.io/logagent
http://数据采集地址/logagent

BatchConsumer は最初にデータをバッファに格納し、データバーが設定された値（batchSize、デフォルトは 20）を超えると、レポートをトリガーします BatchConsumer を作成するときに batchSize を指定することもできます

// 创建 BatchConsumer, 指定接收端地址、APP ID、缓冲区大小，单位为M
consumer, err := thinkingdata.NewBatchConsumerWithBatchSize("SERVER_URL", "APP_ID", 50)

（3）DebugConsumer:データをリアルタイムで TA サーバーに転送し、データ形式が間違っている場合は詳細なエラー情報を返します。最初に DebugConsumer 検証データ形式を使用することをお勧めしますが、本番環境での使用

consumer, _ := thinkingdata.NewDebugConsumer("SERVER_URL", "APP_ID")

データを入庫したくない場合、データ形式をチェックしたい場合は、次のようにコードを初期化できます

//默认是true，代表入库
consumer, _ := thinkingdata.NewDebugConsumerWithWriter("SERVER_URL", "APP_ID",false)

SERVER_URLは転送データの URL、APP_IDはプロジェクトの APP ID

クラウドサービスを使用している場合は、次の URL を入力してください

http://ta-receiver.thinkingdata.io

民営化された展開のバージョンを使用している場合は、次の URL を入力してください

http://数据采集地址

1.3 SDK インスタンスの作成

作成されたConsumerすると、対応する TDAnalytics インスタンスが得られます

ta, err := thinkingdata.New(consumer)

その後、ta インターフェイスを使用してデータを報告できます

二、データを報告する

SDK の初期化が完了すると、trackを呼び出してイベントをアップロードできます。通常、ダースから数百の異なるイベントをアップロードする必要があります。

どのようなイベントを送信する必要があるか疑問がある場合は、クイッククイック使用ガイドください。

2.1 送信イベント

を呼び出してtrackイベントをアップロードすることができます。イベントのプロパティと情報を送信する条件を設定することを

// 设置事件属性
properties := map[string]interface{}{
    // 系统预置属性, 可选. "#time" 属性是系统预置属性，传入 time.Time 对象，也可以上传符合TA的时间字符串，表示事件发生的时间
    // 如果不填入该属性，则默认使用系统当前时间
    //"#time": time.Now().UTC(),
    //"#time":"2020-02-02 11:49:43.222",
    // 系统预置属性, 可选. 如果服务端中能获取用户 IP 地址, 并填入该属性
    // 数数会自动根据 IP 地址解析用户的省份、城市信息
    "#ip": "123.123.123.123",
    // 用户自定义属性, 字符串类型
    "prop_string": "abcdefg",
    // 用户自定义属性, 数值类型
    "prop_num": 56.56,
    // 用户自定义属性, bool 类型
    "prop_bool": true,
    // 用户自定义属性, time.Time 类型
	"prop_date": time.Now(),
}

account_id := "user_account_id" // 账号 ID
distinct_id := "ABCDEF123456AGDCDD" // 访客 ID

// 上报事件名为 TEST_EVENT 的事件. account_id 和 distinct_id 不能同时为空
ta.Track(account_id, distinct_id, "TEST_EVENT", properties)

**注:**ビジター ID とアカウント ID がスムーズにバインドされることを保証するために、ゲームにビジター ID とアカウント ID が使用される場合は、この 2 つの ID を同時にアップロードすることを強くお勧めします。そうしないと、アカウントが一致しない状況が発生し、ユーザーが計算を繰り返すことになります。具体的な ID バインドルールはユーザー識別ルールの章を参考ユーザー識別ルールにしてください。

• イベントの名前はアルファベットのみで始まり、数字、文字、下線の「_」を含めることができ、長さは最大 50 文字で、文字の大文字と小文字には敏感ではない
• イベントのプロパティはマップ型で、各要素はプロパティ
• イベントプロパティの Key 値はプロパティの名前で、string型で、文字で始まることができ、数字、文字、下線「_」を含み、長さは最大 50 文字で、文字の大文字と小文字には敏感ではない
• イベントプロパティの Value 値は、文字列、、、数値型、bool、timeをサポートTimeと配列型

2.2 パブリックイベントプロパティの設定

すべてのイベントに表示する必要があるプロパティの一部については、SetSuperPropertiesを呼び出して共通イベントプロパティを設定できます。イベントを送信する前に、共通イベントプロパティを設定することをお勧めします。

// 设置公共事件属性
ta.SetSuperProperties(map[string]interface{}{
	"SUPER_TIME":   time.Now(),
	"SUPER_BOOL":   true,
	"SUPER_STRING": "hello",
	"SUPER_NUM":    15.6,
})

• 共通イベントプロパティはmap型で、各要素はプロパティ
• 共通イベントプロパティの Key 値はプロパティの名前で、string型で、文字で始まることができ、数字、文字、下線「_」を含み、長さは最大 50 文字で、文字の大文字と小文字には敏感ではない
• 共通イベントプロパティの Value 値は、文字列、、、数値型、bool、timeをサポートTimeと配列型

共通属性を設定することは、すべてのイベントに上記の属性を設定することに相当し、イベント内の属性が共通属性と名前を変更すると、そのデータのイベント属性が同名の共通イベント属性を上書きする。同じ名前の属性が存在しない場合は、この属性を追加して、現在の共通イベント属性をインターフェイスから取得できます

currentSuperProperties := ta.GetSuperProperties()

を呼び出すとClearSuperPropertiesをクリアできます。

ta.ClearSuperProperties()

三、ユーザー属性

TA プラットフォームで現在サポートされているユーザープロパティ設定インターフェイスはUserSet、UserSetOnce、UserAdd、UserDelete、UserUnset、UserAppend。

3.1 ユーザーセット

一般的なユーザープロパティの場合は、UserSetを呼び出して設定できますこのインターフェイスを使用してアップロードされた属性は、そのユーザーの元のユーザー属性を上書きし、以前に存在しなかった場合は、新しいユーザー属性を作成します

ta.UserSet(account_id, distinct_id, map[string]interface{}{
	"USER_STRING": "some message",
	"USER_DATE":   time.Now(),
})

//再次上传用户属性，该用户的"USER_STRING"被覆盖为"another message"

ta.UserSet(account_id, distinct_id, map[string]interface{}{
	"USER_STRING": "another message"
})

• UserSet設定のユーザープロパティはマップ型で、各要素はプロパティ
• ユーザー属性Keyは属性名で、string型で、文字で始まることができ、数字、文字、下線「_」を含み、長さは最大 50 文字で、文字の大文字と小文字には敏感ではない
• 属性値は 5 種類をサポート:サポートstring、数値型、bool、time。Timeと配列型

3.2 User SetOnce

アップロードしたユーザープロパティを一度だけ設定する場合は、UserSetOnceを呼び出して設定できます。

ta.UserSetOnce(account_id, distinct_id, map[string]interface{}{
	"USER_STRING": "some message",
	"USER_DATE":   time.Now(),
})
//再次上传用户属性，该用户的"USER_STRING"仍为"some message"

ta.UserSetOnce(account_id, distinct_id, map[string]interface{}{
	"USER_STRING": "another message"
})

//再次使用UserSet上传用户属性，该用户的"USER_STRING"会被覆盖为"other message"

ta.UserSet(account_id, distinct_id, map[string]interface{}{
	"USER_STRING": "other message"
})

UserSetOnce設定のユーザープロパティの種類と制限はUserSet一致します。

3.3 UserAdd

数値型のプロパティをアップロードするときは、UserAdd を呼び出しUserAdd、プロパティを累積的に操作することができます。プロパティが設定されていない場合は、0 を割り当ててから計算します。負の値が渡され、減算操作に相当します。

ta.UserAdd(account_id, distinct_id, map[string]interface{}{
	"Amount": 50,
})

//再次上传用户属性，该用户的"Amount"现为80

ta.UserAdd(account_id, distinct_id, map[string]interface{}{
	"Amount": 30,
})

UserAdd設定のユーザープロパティの種類と制限はUserSet一致しますが、数値型のユーザープロパティにのみ有効です。

3.4 ユーザー削除

を削除する場合は、UserDelete を呼び出しUserDeleteて削除できますが、ユーザーのユーザープロパティを照会することはできません

ta.UserDelete(account_id, distinct_id)

3.5 UserUnset

ユーザーのユーザープロパティの値を空にする必要がある場合は、UserUnset を呼び出し呼び出して空にします

// 清空某个用户的某个用户属性，在参数中传入属性名
ta.UserUnset(account_id, distinct_id, property_name)

3.6 UserAppend

配列型にユーザープロパティ値を追加する場合は、user_appendを呼び出して、指定されたプロパティを追加でき。

//用户数组类型追加属性 UserAppend ,为下面两个数组类型添加以下属性，只支持key - []string
    err = ta.UserAppend(account_id, distinct_id, map[string]interface{}{
    		"array": []string{"str1","str2"},
    		"arrkey1":[]string{"str3","str4"},
    	})
    if err != nil {
    	fmt.Println("user add failed", err)
    }

四、その他の操作

4.1 即時データ提出

この操作は、特定の Consumer 実装に関連していますデータを受信すると、Consumer は最初にバッファにデータを保存し、特定の場合に真のデータ IO 操作をトリガーして全体的なパフォーマンスを向上させることができます場合によってはすぐにデータを送信する必要があり、Flush インターフェイス

// 立即提交数据到相应的接收端
ta.Flush()

4.2 SDK のシャットダウン

BatchConsumer は、サーバーがシャットダウンまたは SDK が終了する前に Close メソッドを実行する必要があります。

// 关闭并退出 SDK
ta.Close()

sdk を閉じて終了し、サーバーを閉じる前にこのインターフェイスを呼び出して、キャッシュ内のデータが失わ

V.関連するプリセットプロパティ

5.1 すべてのイベントのプリセットプロパティ

次のプリセットプロパティは、Go SDK のすべてのイベント(自動取得イベントを含む)に含まれるプリセットプロパティ

プロパティ名	中国語の	説明
#ip	IPアドレス	ユーザーのIPアドレスは、手動で設定する必要があり、TAはユーザーの地理的位置情報
#国	国	ユーザーの国は、IPアドレスに基づいて生成されます
#カントリーコード	国コード	ユーザーがいる国の国コード(ISO 3166-1 alpha-2、つまり2大文字英字)は、IPアドレスに基づいて生成
#県	州	ユーザーの州、IPアドレスに基づいて生成
#都市	都市	ユーザーの都市は、IPアドレスに基づいて生成されます
#lib	SDKタイプ	SDKにアクセスするタイプ(tga_go_sdkなど)
#リブバージョン	SDKバージョン	Go SDKのバージョンにアクセスします

六、高度な機能

v1.2.0 以降、SDK では、更新可能イベントと書き換え可能イベントの 2 種類のイベントの報告がサポートされています。両方のイベントは、TA システム 2.8 以降のバージョンで使用する必要があります。特殊なイベントは特定の場面でしか適用されないので、数値計算技術の顧客成功とアナリストの助けを得て、特殊なイベントを使ってデータを報告してください。

6.1 更新可能イベント

更新可能なイベントを使用すると、特定のシナリオでイベントデータを変更する必要がある要件を満たすことができます。更新可能なイベントには、イベントを識別する ID を指定し、更新可能なイベントオブジェクトを作成するときに着信する必要があります。TA バックグラウンドは、イベント名とイベント ID に基づいて更新するデータを決定します。

// 示例： 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT
proterties := make(map[string]interface{})
properties["status"] = 3
properties["price"] = 100

consumer, _ := thinkingdata.NewBatchConsumer("url", "appid")
ta := thinkingdata.New(consumer)

// 上报后事件属性 status 为 3, price 为 100
ta.TrackUpdate("account_id", "distinct_id", "UPDATABLE_EVENT", "test_event_id", properties))

proterties_new := make(map[string]interface{})
proterties_new["status"] = 5

// 上报后事件属性 status 被更新为 5, price 不变
ta.TrackUpdate("account_id", "distinct_id", "UPDATABLE_EVENT", "test_event_id", proterties_new))

6.2 書き換え可能イベント

書き換え可能イベントは更新可能イベントと類似しており、書き換え可能イベントは最新のデータで履歴データを完全にカバーし、効果的には前のデータを削除し、最新のデータを入庫することに相当する。TA バックグラウンドは、イベント名とイベント ID に基づいて更新するデータを決定します。

// 示例： 上报可被重写的事件，假设事件名为 OVERWRITE_EVENT
proterties := make(map[string]interface{})
properties["status"] = 3
properties["price"] = 100

consumer, _ := thinkingdata.NewBatchConsumer("url", "appid")
ta := thinkingdata.New(consumer)

// 上报后事件属性 status 为 3, price 为 100
ta.TrackOverwrite("account_id", "distinct_id", "OVERWRITE_EVENT", "test_event_id", properties))

proterties_new := make(map[string]interface{})
proterties_new["status"] = 5

// 上报后事件属性 status 被更新为 5, price 属性被删除
ta.TrackOverwrite("account_id", "distinct_id", "OVERWRITE_EVENT", "test_event_id", proterties_new))

チェンジログ

v1.5.0 2021/11/02

• 複雑な構造タイプをサポート

v1.4.0 2021/05/10

• BatchConsumer 最適化:ネットワーク接続が切断されたときにデータをキャッシュ

v1.3.0 2020/11/25

• LogConsumer 最適化:ディレクトリの自動作成
• 最適化:自動アップロード機能

v1.2.0 2020/08/24

• 更新可能なイベントと書き換え可能なイベント

v1.1.1 2020/07/08

• フィールド#time は、TA フォーマットに準拠した文字列のアップロードをサポート
• フィールドの 2k サイズの制限を取り除く

v1.1.0 2020/02/12

• 報告配列型のサポート
• UserAppend インターフェイスのサポート
• DebugConsumer 最適化:サービス側でデータをより完全かつ正確に検証
• BatchConsumer パフォーマンスの最適化:圧縮モードの設定、Base64 エンコーディングの削除

v1.0.2 2019/12/25

• UserUnset インターフェイスのサポート

v1.0.1 2019/12/12

• 修正空のプロパティ値がログに書き込まれません

v1.0.0 2019/09/25

• データ報告のコア機能
  • Track:ユーザー行動イベントの追跡
  • 共通イベントプロパティ設定
  • ユーザープロパティ設定: UserSet, UserSetOnce, UserAdd, UserDelete
• サポート: LogConsumer, DebugConsumer, BatchConsumer