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