Go SDK

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

Install the SDK

Install the dependencies.

go 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 constructs a Config struct. Use that Config struct to initialize a client struct that implements the Client interface. You can use the client across requests after you initialize it. Refer to the examples in the next section.

import (
    "github.com/amplitude/analytics-go/amplitude"
)

config := amplitude.NewConfig(AMPLITUDE_API_KEY)

client := amplitude.NewClient(config)

Configure the SDK

Set your configuration before you initialize a client.

Configure batching behavior

To support high-performance environments, the SDK sends events in batches. The SDK queues every event logged by the track method in memory and flushes events in batches in the background. You can customize batch behavior with FlushQueueSize and FlushInterval. By default, the SDK runs in regular mode with serverUrl set to https://api2.amplitude.com/2/httpapi. To send large batches of data at a time, switch to batch mode by setting UseBatch to true, which sets setServerUrl to the batch event upload API https://api2.amplitude.com/batch. Both regular mode and batch mode use the same flush queue size and flush intervals.

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)
}

Track an event

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

// 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,
    },
})

User properties

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

Use Identify to set 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 SDK declares the operations as Identify struct methods. You can chain multiple operations together in a single Identify struct, then pass the struct to the Amplitude client to send to the server.

The Identify struct provides controls over setting user properties. First instantiate an Identify struct, then call Client.Identify() methods on it.

identifyObj := amplitude.Identify{}
client.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 for a user.

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

Identify.SetOnce

This method sets the value of a user property only once. SetOnce() ignores subsequent calls. For example, you can set an initial login method for a user. The SDK tracks only the initial value.

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

Identify.Add

This method increments a user property by a numerical value. If the user property doesn't have a value set yet, the SDK initializes the property to 0 before incrementing it. For example, you can track a user's travel count.

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

Arrays in user properties

You can use arrays 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, the SDK initializes the property to an empty list before prepending the new values.

identifyObj := amplitude.Identify{}
identifyObj.Prepend("visited-locations", "LAX")
client.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, the SDK initializes the property to an empty list before appending the new values.

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

Identify.PreInsert

This method pre-inserts a value or values to a user property if the value 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, the SDK initializes the property to an empty list before pre-inserting the new values. If the user property has an existing value, the SDK performs no operation.

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

Identify.PostInsert

This method post-inserts a value or values to a user property if the value 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, the SDK initializes the property to an empty list before post-inserting the new values. If the user property has an existing value, the SDK performs no operation.

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

Identify.Remove

This method removes a value or values from a user property if the value 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, the SDK performs no operation.

identifyObj := amplitude.Identify{}
identifyObj.Remove("unique-locations", "JFK")
client.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. For example, you can group your users by the organization they're in by using an orgId. You can designate Joe to be in orgId 10 and Sue in orgId 15. When you run a query in Amplitude's Event Segmentation chart, select "..performed by" orgId to query the number of organizations that performed a specific event. As long as at least one member of that group performed the event, Amplitude includes that group in the count.

When you set groups, define a groupType and groupName. In the previous example, orgId is the groupType, and each value, 10 and 15, is a groupName. Another groupType example is sport, with groupName values like tennis and baseball. Use SetGroup() to designate which groups a user belongs to. SetGroup() also sets the groupType:groupName as a user property. SetGroup() overwrites any existing groupName value set for that user's groupType, and the corresponding user property value. groupType is a string, and groupName is an array of strings to show that a user belongs to one group or multiple groups. For example, if Joe is in orgId 10 and 16, the groupName is [10, 16]. Your code might look like this:

// 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"})

Set event-level groups using the Groups attribute of events:

// 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 properties

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

The GroupIdentify() method accepts a group type, a group name string parameter, and an Identify struct to apply to the group.

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

Track revenue

The preferred method of tracking revenue for a user is to use Revenue() with the Revenue interface. The Revenue struct stores each revenue transaction and lets you define several special revenue properties, such as RevenueType and ProductID, that Amplitude's Event Segmentation and Revenue LTV charts use. Pass these Revenue structs into Revenue to send as revenue events to Amplitude. Amplitude then automatically displays revenue-relevant data in the platform. You can 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, a user purchased 3 units of a product at $3.99.

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

Revenue interface

Flush

The Flush method triggers the client to send buffered events.

client.Flush()

Shutdown

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

client.Shutdown()

Plugins

Plugins let you extend the Amplitude SDK's behavior. For example, you can modify event properties (enrichment type) or send events to third-party APIs (destination type). A plugin is a struct with Setup() and Execute() methods.

Client.Add

The Add method adds a plugin to the Amplitude Client struct. Plugins can help process and send events.

client.Add(pluginObj)

Client.Remove

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

client.Remove(pluginName)

Plugin.Setup

This method contains logic that prepares the plugin for use and takes a 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. The SDK calls this method when you register the plugin to the client through client.Add().

Plugin.Execute

This method contains the logic for processing events and takes *Event as a parameter. If you use the plugin as an enrichment type plugin, the expected return value is the modified or enriched event. If you use the plugin as a destination type plugin, the expected return value is a map with keys: event (BaseEvent), code (number), and message (string). The SDK calls this method 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 instrumented event by adding an increment integer to the EventID property of an event.

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{})
}

Destination type plugin

Here's an example of a plugin that sends each instrumented event to a target server 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",
    })
}

The previous example sends an HTTP POST request with a body in JSON format:

{
  "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"
}