Go SDK

The Go SDK lets you send events to Amplitude from your Go application.

Install the SDK

Install the dependencies.

1go get github.com/amplitude/analytics-go

Initialize the SDK

You must initialize the SDK before you can instrument any events. The API key for your Amplitude project is required to construct a Config struct. Use that Config struct to initialize a client struct which implements Client interface. You can use it across requests after it's initialized. See examples in the next section.

1import (
2    "github.com/amplitude/analytics-go/amplitude"
3)
4 
5config := amplitude.NewConfig(AMPLITUDE_API_KEY)
6 
7client := amplitude.NewClient(config)

Configure the SDK

Set your configuration before a client is initialized.

Configure batching behavior

To support high-performance environments, the SDK sends events in batches. Every event logged by track method is queued in memory. Events are flushed in batches in background. You can customize batch behavior with FlushQueueSize and FlushInterval. By default, the SDK is in regular mode with serverUrl to https://api2.amplitude.com/2/httpapi. For customers who want to send large batches of data at a time, switch to batch mode by setting UseBatch to true to set setServerUrl to batch event upload API https://api2.amplitude.com/batch. Both the regular mode and the batch mode use the same flush queue size and flush intervals.

 1package main
 2 
 3import (
 4    "github.com/amplitude/analytics-go/amplitude"
 5)
 6 
 7func main() {
 8    // Create a Config struct
 9    config := amplitude.NewConfig(AMPLITUDE_API_KEY)
10 
11    // Events queued in memory will flush when number of events exceed upload threshold
12    // Default value is 200
13    config.FlushQueueSize = 100
14    // Events queue will flush every certain milliseconds based on setting
15    // Default value is 10 seconds
16    config.FlushInterval = 5000
17    // Pass a Config struct
18    // to initialize a Client struct
19    // which implements Client interface
20    client := amplitude.NewClient(config)
21}

Track an event

Events represent how users interact with your application. For example, "Button Clicked" may be an action you want to note.

 1// Track a basic event
 2// EventOne of UserID and DeviceID is required as well as EventType
 3client.Track(amplitude.Event{
 4    UserID:    "user-id",
 5    EventType: "Button Clicked",
 6})
 7 
 8// Track events with optional properties
 9client.Track(amplitude.Event{
10    UserID:    "user-id",
11    EventType: "Button Clicked",
12    EventProperties: map[string]interface{}{
13        "name":       "Checkout",
14        "a property": "a value",
15    },
16    EventOptions: amplitude.EventOptions{
17        Price: 1.99,
18    },
19})

User properties

User properties help you understand your users at the time they perform some actions within your app such as their device details, their preferences, or languages.

Identify is for setting the user properties of a particular user without sending any event. The SDK supports the operations Set, SetOnce, Unset, Add, Append, Prepend, PreInsert, PostInsert,Remove, and ClearAll on individual user properties. The operations are declared as Identify struct methods. Multiple operations can be chained together in a single Identify struct which is then passed to the Amplitude client to send to the server.

Identify struct provides controls over setting user properties. An Identify struct must first be instantiated, then Client.Identify() methods can be called on it.

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

Identify.Set

This method sets the value of a user property. For example, you can set a role property of a user.

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

Identify.SetOnce

This method sets the value of a user property only once. Subsequent calls using SetOnce() will be ignored. For example, you can set an initial login method for a user and since only the initial value is tracked, SetOnce() ignores subsequent calls.

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

Identify.Add

This method increments a user property by some numerical value. If the user property doesn't have a value set yet, it will be initialized to 0 before being incremented. For example, you can track a user's travel count.

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

Arrays in user properties

Arrays can be used as user properties. You can directly set arrays or use Prepend(), Append(), PreInsert() and PostInsert() to generate an array.

Identify.Prepend

This method prepends a value or values to a user property array. If the user property doesn't have a value set yet, it will be initialized to an empty list before the new values are prepended.

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

Identify.Append

This method appends a value or values to a user property array. If the user property doesn't have a value set yet, it will be initialized to an empty list before the new values are appended.

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

Identify.PreInsert

This method pre-inserts a value or values to a user property if it doesn't exist in the user property yet. Pre-insert means inserting the value at the beginning of a given list. If the user property doesn't have a value set yet, it will be initialized to an empty list before the new values are pre-inserted. If the user property has an existing value, it will be no operation.

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

Identify.PostInsert

This method post-inserts a value or values to a user property if it doesn't exist in the user property yet. Post-insert means inserting the value at the end of a given list. If the user property doesn't have a value set yet, it will be initialized to an empty list before the new values are post-inserted. If the user property has an existing value, it will be no operation.

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

Identify.Remove

This method removes a value or values to a user property if it exists in the user property. Remove means remove the existing value from the given list. If the item doesn't exist in the user property, it will be no operation.

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

User groups

Amplitude supports assigning users to groups and performing queries such as Count by Distinct on those groups. An example would be if you want to group your users based on what organization they're in by using an 'orgId'. You can designate Joe to be in 'orgId' '10' while Sue is in 'orgId' '15'. When performing a query in Amplitude's Event Segmentation chart, you can then select "..performed by" 'orgId' to query the number of different organizations that have performed a specific event. As long as at least one member of that group has performed the specific event, that group will be included in the count.

When setting groups, you need to define a groupType and groupName. In the above example, 'orgId' is the groupType and each value, '10' and '15', is a groupName. Another example of a groupType could be 'sport' with groupName values like 'tennis' and 'baseball'. You can use SetGroup() to designate which groups a user belongs to. Note: This also sets the groupType:groupName as a user property. This overwrites any existing groupName value set for that user's groupType, as well as the corresponding user property value. groupType is a string and groupName is an array of strings to show that a user being in one group or in multiple groups (for example, if Joe is in 'orgId' '10' and '16', then the groupName would be '[10, 16]'). Here is what your code might look like.

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

Event level groups are set by Groups attribute of events

 1// set groups when initial an Event struct
 2event := amplitude.Event{
 3    UserID:          "user-id",
 4    EventType:       "event-type",
 5    Groups: map[string][]string{"org-id": {"15", "21"}},
 6  }
 7 
 8// set groups for an existing Event struct
 9event.Groups["Sport"] = []string{"soccer"}
10 
11client.Track(event)

Group properties

Use the Group Identify API to set or update the properties of particular groups. However, these updates will only affect events going forward.

The GroupIdentify() method accepts a group type and group name string parameter, as well as an Identify struct that will be applied to the group.

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

Track revenue

The preferred method of tracking revenue for a user is to use Revenue() in conjunction with the provided Revenue interface. Revenue struct stores each revenue transaction and allow you to define several special revenue properties (such as 'RevenueType' and 'ProductID') that are used in Amplitude's Event Segmentation and Revenue LTV charts. These Revenue struct are then passed into Revenue to send as revenue events to Amplitude. This allows Amplitude to automatically display data relevant to revenue in the platform. You can use this to track both in-app and non-in-app purchases.

To track revenue from a user, call Revenue() each time a user generates revenue. For example, 3 units of a product were purchased at $3.99.

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

Revenue Interface

Flush

The Flush method triggers the client to send buffered events.

1client.Flush()

Shutdown

The Shutdown method closes the Client struct. A closed Client struct won't accept new events and tries to flush events in the buffer. Then the Client struct shuts down running threads.

1client.Shutdown()

Plugins

Plugins allow you to extend Amplitude SDK's behavior by, for example, modifying event properties (enrichment type) or sending to third-party APIs (destination type). A plugin is struct with methods Setup() and Execute().

Client.Add

The Add method adds a plugin to Amplitude Client struct. Plugins can help processing and sending events.

1client.Add(pluginObj)

Client.Remove

The Remove method removes the given plugin from the Client struct if exists.

1client.Remove(pluginName)

Plugin.Setup

This method contains logic for preparing the plugin for use and has Config struct as a parameter. The expected return value is nil. A typical use for this method, is to copy configuration from Config or instantiate plugin dependencies. This method is called when you register the plugin to the client via client.Add().

Plugin.Execute

This method contains the logic for processing events and has *Event as parameter. If used as enrichment type plugin, the expected return value is the modified/enriched event. If used as a destination type plugin, the expected return value is a map with keys: event (BaseEvent), code (number), and message (string). This method is called for each event instrumented using the client interface, including Identify, GroupIdentify and Revenue events.

Plugin examples

Enrichment type plugin

Here's an example of a plugin that modifies each event that's instrumented by adding an increment integer to EventID property of an event.

 1package main
 2 
 3import "github.com/amplitude/analytics-go/amplitude"
 4 
 5type addEventIDPlugin struct {
 6    currentID int
 7    config    amplitude.Config
 8}
 9 
10func (plugin *addEventIDPlugin) Name() string {
11    return "AddEventId"
12}
13 
14func (plugin *addEventIDPlugin) Setup(config amplitude.Config) {
15    plugin.config = config
16}
17 
18func (plugin *addEventIDPlugin) Type() amplitude.PluginType {
19    return amplitude.PluginTypeEnrichment
20}
21 
22func (plugin *addEventIDPlugin) Execute(event *amplitude.Event) *amplitude.Event {
23    event.EventID = plugin.currentID
24    plugin.currentID += 1
25    return event
26}
27 
28func main() {
29    config := amplitude.NewConfig(AMPLITUDE_API_KEY)
30    client := amplitude.NewClient(config)
31    defer client.Shutdown()
32 
33    client.Add(&addEventIDPlugin{})
34}

Destination type plugin

Here's an example of a plugin that sends each event that's instrumented to a target server URL.

 1package main
 2 
 3import (
 4    "bytes"
 5    "encoding/json"
 6    "net/http"
 7 
 8    "github.com/amplitude/analytics-go/amplitude"
 9)
10 
11type myDestinationPlugin struct {
12    url        string
13    config     amplitude.Config
14    httpClient http.Client
15}
16 
17func (plugin *myDestinationPlugin) Name() string {
18    return "MyDestinationPlugin"
19}
20 
21// Setup is called on plugin installation
22func (plugin *myDestinationPlugin) Setup(config amplitude.Config) {
23    plugin.config = config
24    plugin.httpClient = http.Client{}
25}
26 
27// Type defines your amplitude.PluginType from:
28//  - amplitude.PluginTypeBefore
29//  - amplitude.PluginTypeEnrichment
30//  - amplitude.PluginTypeDestination
31func (plugin *myDestinationPlugin) Type() amplitude.PluginType {
32    return amplitude.PluginTypeDestination
33}
34 
35// Execute is called on each event instrumented
36func (plugin *myDestinationPlugin) Execute(event *amplitude.Event) {
37    payload := map[string]interface{}{"key": "secret", "events": event}
38    payloadBytes, err := json.Marshal(payload)
39 
40    if err != nil {
41        plugin.config.Logger.Errorf("Event encoding failed: ", err)
42    }
43 
44    request, err := http.NewRequest("POST", plugin.url, bytes.NewReader(payloadBytes))
45    if err != nil {
46        plugin.config.Logger.Errorf("Building new request failed", err)
47    }
48 
49    response, err := plugin.httpClient.Do(request)
50    if err != nil {
51        plugin.config.Logger.Errorf("HTTP request failed", err)
52    } else {
53        defer response.Body.Close()
54    }
55}
56 
57func main() {
58    config := amplitude.NewConfig(AMPLITUDE_API_KEY)
59    client := amplitude.NewClient(config)
60    defer client.Shutdown()
61 
62    client.Add(&myDestinationPlugin{
63        // Change it to your target server URL
64        url: "https://custom.domain.com",
65    })
66 
67    client.Track(amplitude.Event{
68        UserID: "user-id",
69        EventType: "Button Clicked",
70    })
71}

The example above sends a HTTP POST request with a body as JSON format

 1{
 2  "events":
 3    {
 4      "event_type":"Button Clicked",
 5      "user_id":"user-id",
 6      "time":1660683660056,
 7      "insert_id":"1c8aac41-8257-4bea-ab3f-de914e39df5e",
 8      "library":"amplitude-go/0.0.2",
 9      "plan":{}
10    },
11  "key":"secret"
12}