Go SDK

gomodvv1.3.1

Go SDK を使用すると、Go アプリケーションから Amplitude にイベントを送信できます。

SDKをインストールする

依存関係をインストールします。

bash

go get github.com/amplitude/analytics-go

SDKの初期化

イベントをインストルメントするには、まずSDKを初期化する必要があります。AmplitudeプロジェクトのAPIキーは、Config structを構築します。このConfig structを使用して、Clientインターフェースを実装するクライアント structを初期化します。初期化後は、複数のリクエストでクライアントを使用できます。次のセクションの例を参照してください。

import (
    "github.com/amplitude/analytics-go/amplitude"
)
config := amplitude.NewConfig(AMPLITUDE_API_KEY)
client := amplitude.NewClient(config)

SDK を設定する

名前	概要	デフォルト値
`APIKey`	必須です。 `string` AmplitudeプロジェクトのAPIキーです。クライアント`struct`は、このプロジェクトにイベントを送信します。クライアント`struct`を初期化するときにこの値を設定します。	`nil`
`FlushQueueSize`	`int`。イベントはバッファ内で待機し、バッチで送信されます。イベント数が`FlushQueueSize`に達すると、SDKはバッファをフラッシュします。	`200`
`FlushInterval`	`time.Duration`。イベントはバッファ内で待機し、バッチで送信されます。 SDKは`FlushInterval`ごとにバッファをフラッシュします。	`10 seconds`
`FlushMaxRetries`	`int`。リクエストがエラーを返した場合にクライアントがイベントを再試行する回数。	`12`
`RetryBaseInterval`	`time.Duration`。リクエストがエラーを返したときのリトライ間隔の基本値です。	`100 milliseconds`
`RetryThrottledInterval`	`time.Duration`。スロットリングされたリクエストの再試行間隔の基準値。	`30 seconds`
`Logger`	ロガーインターフェース。Amplitudeクライアントが使用するロガー。	`Go standard Logger`：`log.Logger`。
`ServerZone`	`string`。プロジェクトのサーバーゾーン。 EUと米国に対応しています。EU域内のデータレジデンシーの場合は、EUに変更してください。	`US`
`ServerURL`	`string`。 SDKがイベントを送信するAPIエンドポイントのURL。`ServerZone`および`UseBatch`によってこのURLは自動的に選択されます。このフィールドを設定すると、SDKは`ServerZone`と`UseBatch`を無視し、文字列値を使用します。	`https://api2.amplitude.com/2/httpapi`
`UseBatch`	`boolean`。バッチ API を使用するかどうか。デフォルトでは、SDKはデフォルトの`serverUrl`を使用します。	`false`
`StorageFactory`	`function`。ストレージバッファにイベントを保持するストレージ構造体を作成します。ストレージバッファ内のイベントは送信を待機しています。	`InMemoryStorage`
`OptOut`	`bool`。オプトアウトオプション。 `true`に設定されている場合、クライアントはイベントを処理または送信しません。	`false`
`ConnectionTimeout`	`time.Duration`。 API リクエストの時間制限。	`10 seconds`
`MaxStorageCapacity`	`int`。ストレージ内の保留中のイベントの最大数。	`20000`
`MinIDLength`	`int`。 user_idおよびdevice_idの最小長です。	`5`
`ExecuteCallback`	`function`。クライアントレベルのコールバック機能。	`nil`

クライアントを初期化する前に構成を設定してください。

バッチ処理の動作を設定する

高パフォーマンス環境をサポートするために、SDK はイベントをバッチで送信します。 SDKは、trackメソッドによってログに記録されたすべてのイベントをメモリにキューイングし、バックグラウンドでイベントをバッチでフラッシュします。FlushQueueSizeおよび FlushIntervalを使用してバッチ動作をカスタマイズできます。デフォルトでは、SDKはserverUrlがhttps://api2.amplitude.com/2/httpapiに設定されている通常モードで実行されます。一度に大量のデータを送信するには、UseBatchをtrueに設定してバッチモードに切り替えます。これにより、setServerUrlがバッチイベントアップロードAPIhttps://api2.amplitude.com/batchに設定されます。通常モードとバッチモードの両方で、同じフラッシュキューサイズとフラッシュ間隔を使用します。

package main
import (
    "github.com/amplitude/analytics-go/amplitude"
)
func main() {
    // Create a Config struct
    config := amplitude.NewConfig(AMPLITUDE_API_KEY)
    // Events queued in memory will flush when number of events exceed upload threshold
    // Default value is 200
    config.FlushQueueSize = 100
    // Events queue will flush every certain milliseconds based on setting
    // Default value is 10 seconds
    config.FlushInterval = 5000
    // Pass a Config struct
    // to initialize a Client struct
    // which implements Client interface
    client := amplitude.NewClient(config)
}

イベントを追跡する

イベントは、ユーザーがアプリケーションとどのように対話するかを表します。たとえば、「Button Clicked」は、メモしておきたいアクションの1つです。

// Track a basic event
// EventOne of UserID and DeviceID is required as well as EventType
client.Track(amplitude.Event{
    UserID:    "user-id",
    EventType: "Button Clicked",
})
// Track events with optional properties
client.Track(amplitude.Event{
    UserID:    "user-id",
    EventType: "Button Clicked",
    EventProperties: map[string]interface{}{
        "name":       "Checkout",
        "a property": "a value",
    },
    EventOptions: amplitude.EventOptions{
        Price: 1.99,
    },
})

ユーザープロパティ

ユーザープロパティは、ユーザーがアプリ内でアクションを実行する際のユーザーの状況を把握するのに役立ちます（デバイスの詳細、環境設定、言語など）。

Identifyを使用すると、イベントを送信することなく特定のユーザーのユーザープロパティを設定できます。SDKは、個々のユーザープロパティに対する、Set、SetOnce、Unset、Add、Append、Prepend、PreInsert、PostInsert、Remove、およびClearAllなどの操作をサポートしています。 SDKは、操作をIdentifystructメソッドとして宣言します。複数の操作を単一のIdentifystructにまとめてチェーンし、そのstructをAmplitudeクライアントに渡してサーバーに送信することができます。

イベントのあとにIdentifyコールを送信した場合、操作の結果はすぐにダッシュボードのユーザーのプロファイル領域に表示されますが、Identifyコールのあとに別のイベントを送信するまで、チャートの結果には表示されません。Identify コールは、今後のイベントにのみ影響します。詳細については、「ユーザーのプロパティとイベント」を参照してください。

この構造体は、ユーザープロパティの設定を制御します。Identify まずIdentify structをインスタンス化し、次にそれに対してClient.Identify()メソッドを呼び出します。

identifyObj := amplitude.Identify{}
client.Identify(identifyObj, amplitude.EventOptions{UserID: "user-id"})

Identify.Set

このメソッドは、ユーザープロパティの値を設定します。たとえば、ユーザーのロールプロパティを設定できます。

identifyObj := amplitude.Identify{}
identifyObj.Set("location", "LAX")
client.Identify(identifyObj, amplitude.EventOptions{UserID: "user-id"})

Identify.SetOnce

このメソッドはユーザープロパティの値を1回だけ設定します。SetOnce()はその後の呼び出しを無視します。たとえば、ユーザーの初期ログイン方法を設定できます。SDK は初期値のみを追跡します。

identifyObj := amplitude.Identify{}
identifyObj.SetOnce("initial-location", "SFO")
client.Identify(identifyObj, amplitude.EventOptions{UserID: "user-id"})

Identify.Add

このメソッドは、ユーザープロパティの値を数値分増加させます。ユーザープロパティに値がまだ設定されていない場合、SDKはプロパティを0に初期化してから値を増やします。たとえば、ユーザーの旅行回数を追跡できます。

identifyObj := amplitude.Identify{}
identifyObj.Add("travel-count", 1)
client.Identify(identifyObj, amplitude.EventOptions{UserID: "user-id"})

ユーザープロパティ内の配列

配列をユーザープロパティとして使用できます。配列を直接設定することも、Prepend()、Append()、PreInsert()、および PostInsert() を使用して配列を生成することもできます。

Identify.Prepend

このメソッドは、ユーザープロパティ配列の前に値を付加します。ユーザープロパティに値がまだ設定されていない場合、SDKは新しい値を先頭に追加する前にそのプロパティを空のリストに初期化します。

identifyObj := amplitude.Identify{}
identifyObj.Prepend("visited-locations", "LAX")
client.Identify(identifyObj, amplitude.EventOptions{UserID: "user-id"})

Identify.Append

このメソッドは、ユーザープロパティ配列に値を付加します。ユーザープロパティに値がまだ設定されていない場合、SDKは新しい値を追加する前にそのプロパティを空のリストに初期化します。

identifyObj := amplitude.Identify{}
identifyObj.Append("visited-locations", "SFO")
client.Identify(identifyObj, amplitude.EventOptions{UserID: "user-id"})

Identify.PreInsert

このメソッドは、値がユーザープロパティにまだ存在しない場合に、ユーザープロパティに1つまたは複数の値を事前に挿入します。事前挿入とは、指定されたリストの先頭に値を挿入することを意味します。ユーザープロパティに値がまだ設定されていない場合、SDKは新しい値を事前に挿入する前にそのプロパティを空のリストに初期化します。ユーザープロパティに既存の値がある場合、SDKは操作を実行しません。

identifyObj := amplitude.Identify{}
identifyObj.PreInsert("unique-locations", "LAX")
client.Identify(identifyObj, amplitude.EventOptions{UserID: "user-id"})

Identify.PostInsert

このメソッドは、値がユーザープロパティにまだ存在しない場合に、ユーザープロパティに値を事後挿入します。ポスト挿入とは、指定されたリストの最後に値を挿入することを意味します。ユーザープロパティに値がまだ設定されていない場合、SDKは新しい値を挿入する前にそのプロパティを空のリストに初期化します。ユーザープロパティに既存の値がある場合、SDKは操作を実行しません。

identifyObj := amplitude.Identify{}
identifyObj.PostInsert("unique-locations", "SFO")
client.Identify(identifyObj, amplitude.EventOptions{UserID: "user-id"})

Identify.Remove

このメソッドは、値がユーザープロパティに存在する場合に、そのユーザープロパティから値を削除します。 Removeは指定されたリストから既存の値を削除することを意味します。ユーザープロパティにこの項目が存在しない場合、SDKは操作を実行しません。

identifyObj := amplitude.Identify{}
identifyObj.Remove("unique-locations", "JFK")
client.Identify(identifyObj, amplitude.EventOptions{UserID: "user-id"})

ユーザーグループ

Amplitudeでは、ユーザーをグループに割り当てたり、それらのグループに対して「Count by Distinct（ユニーク数による集計）」などのクエリを実行したりすることができます。たとえば、orgIdを使用すれば、ユーザーが所属する組織ごとにユーザーをグループ化できます。JoeをorgId 10に、SueをorgId 15に指定できます。Amplitudeのイベントセグメンテーションチャートでクエリを実行するときに、「..performed by」orgIdを選択して、特定のイベントを実行した組織の数をクエリします。そのグループのメンバーのうち少なくとも1人がイベントを実行している限り、Amplitudeはそのグループをカウントに含めます。

グループを設定する際には、groupTypeとgroupNameを定義してください。前の例では、orgIdはgroupTypeであり、それぞれの値である10と15はgroupNameです。もう1つのgroupTypeの例としてはsportがあり、tennisやbaseballなどの値がgroupNameになります。ユーザーが属するグループを指定するにはSetGroup()を使用します。SetGroup()はまた、groupType:groupNameをユーザープロパティとして設定します。SetGroup()は、そのユーザーのgroupTypeに設定されている既存のgroupName値と、対応するユーザープロパティ値を上書きします。groupTypeは文字列であり、groupNameはユーザーが1つのグループまたは複数のグループに属していることを示す文字列の配列です。たとえば、JoeがorgId 10および16に属する場合、groupNameは[10, 16]になります。コードは次のようになります：

// set group with single group name
client.SetGroup("org-id", []string{"15"}, amplitude.EventOptions{UserID: "user-id"})
// set group with multiple group names
client.SetGroup("org-id", []string{"15", "21"}, amplitude.EventOptions{UserID: "user-id"})

イベントのGroups属性を使用してイベントレベルのグループを設定します。

// set groups when initial an Event struct
event := amplitude.Event{
    UserID:          "user-id",
    EventType:       "event-type",
    Groups: map[string][]string{"org-id": {"15", "21"}},
  }
// set groups for an existing Event struct
event.Groups["Sport"] = []string{"soccer"}
client.Track(event)

グループプロパティ

Group Identify API を使用して、特定のグループのプロパティを設定または更新します。これらの更新プログラムは今後のイベントにのみ影響します。

GroupIdentify()メソッドは、グループタイプ、グループ名の文字列パラメータ、およびIdentify structを受け取り、グループに適用します。

identifyObj := amplitude.Identify{}
identifyObj.Set("local", "en-us")
client.GroupIdentify("org-id", "15", identifyObj, amplitude.EventOptions{})

収益の追跡

ユーザーの収益を追跡する際に推奨される方法は、Revenue()とRevenueインターフェースを組み合わせて使用することです。Revenue structは各収益トランザクションを保存し、AmplitudeのイベントセグメンテーションとレベニューLTVチャートで使用されるRevenueTypeやProductIDなどの複数の特別収益プロパティを定義できます。これらのRevenue structsをRevenueに渡して、収益イベントとしてAmplitudeに送信します。その後、Amplitudeは収益関連データをプラットフォームに自動的に表示します。アプリ内購入とアプリ内購入以外の購入の両方を追跡できます。

ユーザーからの収益を追跡するには、Revenue()ユーザーが収益を上げるたびに電話をかけます。たとえば、あるユーザーがプロダクトを1点につき3.99ドルで3台購入したとします。

revenueObj := amplitude.Revenue{
    Price:       3.99,
    Quantity:    3,
    ProductID:   "com.company.productID",
}
client.Revenue(revenueObj, amplitude.EventOptions{UserID: "user-id"})

収益インターフェイス

名前	タイプ	概要	デフォルト
製品ID（オプション）	文字列	プロダクトの識別子です。 AmplitudeはGoogle PlayストアのプロダクトIDのようなものを推奨しています。	""
数量（オプション）	int	購入された製品の数量。 `Revenue = Quantity * Price`	0
価格（オプション *収益フィールドが設定されていない場合、収益データに必須）	float64	購入されたプロダクトの価格です。負の値を使用して払い戻しを示すことができます。 `Revenue = Quantity * Price`	0
収益タイプ (オプション)	文字列	収益タイプ（税金、払い戻し、収入など）。	""
領収書（オプション）	文字列	収益の領収書識別子です。	""
ReceiptSig (オプション)	文字列	収益の領収書の署名。	""
プロパティ（オプション）	map[string]interface{}	収益イベントに含めるイベントプロパティのマップ。	nil
収益（オプション）	float64	負の値を使用して払い戻しを示します。 `Revenue = Quantity * Price`	0

フラッシュ

このFlushメソッドは、クライアントによるバッファリングされたイベントの送信をトリガーします。

client.Flush()

シャットダウン

ShutdownメソッドはClient structを閉じます。閉じられたClient structは新しいイベントを受け入れず、バッファ内のイベントをフラッシュしようとします。その後、Client structは実行中のスレッドをシャットダウンします。

client.Shutdown()

プラグイン

プラグインを使用すると、Amplitude SDKの動作を拡張できます。たとえば、イベントプロパティを変更したり（拡張タイプ）、イベントをサードパーティ製 API に送信したり（送信先タイプ）できます。プラグインとは、Setup()およびExecute()メソッドを持つstructです。

Client.Add

このAddメソッドは、Amplitude Client structにプラグインを追加します。プラグインはイベントの処理と送信を支援できます。

client.Add(pluginObj)

Client.Remove

このRemoveメソッドは、Client structから指定されたプラグインを削除します（存在する場合）。

client.Remove(pluginName)

Plugin.Setup

このメソッドには、プラグインを使用できるように準備するロジックが含まれており、Config structをパラメータとして受け取ります。期待される戻り値は nil です。このメソッドの一般的な用途は、Configから設定をコピーしたり、プラグインの依存関係をインスタンス化したりすることです。SDKは、client.Add()を通じてプラグインをクライアントに登録する際に、このメソッドを呼び出します。

Plugin.Execute

このメソッドにはイベントを処理するためのロジックが含まれており、*Eventをパラメータとして受け取ります。プラグインを拡張タイプのプラグインとして使用する場合、期待される戻り値は変更されたイベントまたは拡張されたイベントです。このプラグインを送信先送信先タイプのプラグインとして使用する場合、期待される戻り値は、キーとしてevent（BaseEvent）、code（数値）、message（文字列）を持つマップです。SDKは、Identify、GroupIdentify、およびRevenueイベントなど、クライアントインターフェイスを使用して計測される各イベントに対してこのメソッドを呼び出します。

プラグインの例

エンリッチメントタイプのプラグイン

以下は、イベントのEventIDプロパティに増分整数を追加することにより、計測対象の各イベントを変更するプラグインの例です。

package main
import "github.com/amplitude/analytics-go/amplitude"
type addEventIDPlugin struct {
    currentID int
    config    amplitude.Config
}
func (plugin *addEventIDPlugin) Name() string {
    return "AddEventId"
}
func (plugin *addEventIDPlugin) Setup(config amplitude.Config) {
    plugin.config = config
}
func (plugin *addEventIDPlugin) Type() amplitude.PluginType {
    return amplitude.PluginTypeEnrichment
}
func (plugin *addEventIDPlugin) Execute(event *amplitude.Event) *amplitude.Event {
    event.EventID = plugin.currentID
    plugin.currentID += 1
    return event
}
func main() {
    config := amplitude.NewConfig(AMPLITUDE_API_KEY)
    client := amplitude.NewClient(config)
    defer client.Shutdown()
    client.Add(&addEventIDPlugin{})
}

送信先タイプのプラグイン

以下は、インストルメンテーションされた各イベントをターゲットサーバーのURLに送信するプラグインの例です。

package main
import (
    "bytes"
    "encoding/json"
    "net/http"
    "github.com/amplitude/analytics-go/amplitude"
)
type myDestinationPlugin struct {
    url        string
    config     amplitude.Config
    httpClient http.Client
}
func (plugin *myDestinationPlugin) Name() string {
    return "MyDestinationPlugin"
}
// Setup is called on plugin installation
func (plugin *myDestinationPlugin) Setup(config amplitude.Config) {
    plugin.config = config
    plugin.httpClient = http.Client{}
}
// Type defines your amplitude.PluginType from:
//  - amplitude.PluginTypeBefore
//  - amplitude.PluginTypeEnrichment
//  - amplitude.PluginTypeDestination
func (plugin *myDestinationPlugin) Type() amplitude.PluginType {
    return amplitude.PluginTypeDestination
}
// Execute is called on each event instrumented
func (plugin *myDestinationPlugin) Execute(event *amplitude.Event) {
    payload := map[string]interface{}{"key": "secret", "events": event}
    payloadBytes, err := json.Marshal(payload)
    if err != nil {
        plugin.config.Logger.Errorf("Event encoding failed: ", err)
    }
    request, err := http.NewRequest("POST", plugin.url, bytes.NewReader(payloadBytes))
    if err != nil {
        plugin.config.Logger.Errorf("Building new request failed", err)
    }
    response, err := plugin.httpClient.Do(request)
    if err != nil {
        plugin.config.Logger.Errorf("HTTP request failed", err)
    } else {
        defer response.Body.Close()
    }
}
func main() {
    config := amplitude.NewConfig(AMPLITUDE_API_KEY)
    client := amplitude.NewClient(config)
    defer client.Shutdown()
    client.Add(&myDestinationPlugin{
        // Change it to your target server URL
        url: "https://custom.domain.com",
    })
    client.Track(amplitude.Event{
        UserID: "user-id",
        EventType: "Button Clicked",
    })
}

前の例では、JSON 形式の本文を持つ HTTP POST リクエストを送信しています。

json

{
  "events": {
    "event_type": "Button Clicked",
    "user_id": "user-id",
    "time": 1660683660056,
    "insert_id": "1c8aac41-8257-4bea-ab3f-de914e39df5e",
    "library": "amplitude-go/0.0.2",
    "plan": {}
  },
  "key": "secret"
}

Was this helpful?