Ampli for Go

Amplitude Data supports tracking analytics events from Go apps. The generated tracking library is packaged as a Go package.

Quick start

1. (Prerequisite) Create a Tracking Plan in Amplitude Data

   Plan your events and properties in Amplitude Data. For detailed instructions, refer to Create a tracking plan.

2. Install the Amplitude SDK

   shell

   Copy

   go get github.com/amplitude/analytics-go
   

3. Install the Ampli CLI

   shell

   Copy

   npm install -g @amplitude/ampli
   

4. Pull the Ampli Wrapper into your project

   shell

   Copy

   ampli pull [--path ./ampli]
   

5. Initialize the Ampli Wrapper

   go

   API keyCopy

   import "<your-module-name>/ampli"
   
   ampli.Instance.Load(ampli.LoadOptions{
       Client: ampli.LoadClientOptions{
           Configuration: ampli.NewClientConfig(AMPLITUDE_API_KEY),
       },
   })
   

6. Identify users and set user properties

   go

   Copy

   ampli.Instance.Identify(userID, ampli.Identify.Builder().
       UserProp("A trait associated with this user").
       Build(),
   )
   

7. Track events with strongly typed methods and classes

   go

   Copy

   ampli.Instance.SongPlayed("user_id", ampli.SongPlayed.Builder().SongId("song-1").Build())
   ampli.Instance.Track("user_id", ampli.SongFavorited.Builder().SongId("song-2").Build())
   

8. Flush events before application exit

   go

   Copy

   ampli.Instance.Flush()
   

9. Verify implementation status with CLI

   shell

   Copy

   ampli status [--update]
   

Install the SDK

If you haven't already, install the core Amplitude SDK dependency analytics-go using go get.

go get github.com/amplitude/analytics-go

Install Ampli CLI

Install the Ampli CLI from Homebrew or NPM.

brew tap amplitude/ampli
brew install ampli

Pull the Ampli Wrapper into your project

Run the Ampli CLI pull command to log in to Amplitude Data and download the strongly typed Ampli Wrapper for your tracking plan. Run Ampli CLI commands from the project root directory.

ampli pull

Ampli API

Ampli supports the following methods.

Load

Initialize Ampli in your code. The Load() method requires a configuration options parameter:

import  "<your-module-name>/ampli"

ampli.Instance.Load(ampli.LoadOptions{
  Client: ampli.LoadClientOptions{
    Configuration: ampli.NewClientConfig(AMPLITUDE_API_KEY),
  },
})

Identify

Call Identify() to identify a user in your app and associate all future events with their identity, or to set their properties.

Ampli creates types for user properties, just as it does for events and event properties.

The Identify() function accepts a string userID, an Identify event instance, and optional amplitude.EventOptions.

Pass all properties as parameters of methods on ampli.Identify.Builder(). For example, your tracking plan contains a required user property called role. The property's type is a string.

ampli.Instance.Identify(
    "user_id",
    ampli.Identify.Builder().Role("admin").Build(),
)

Use the options argument to pass Amplitude fields for this call, such as DeviceID.

ampli.Instance.Identify(
    "user_id",
    ampli.Identify.Builder().Role("admin").Build(),
    amplitude.EventOptions{
        DeviceID: "device_id",
    },
)

Groups

The Amplitude Go SDK and Go Ampli Wrapper don't support Groups. If you want this feature, submit a feature request through the widget on the Amplitude dashboard, or through a support ticket.

Track

To track an event, call the event's corresponding function. Every event in your tracking plan gets its own function in the Ampli Wrapper. The call has this structure:

ampli.Instance.EventName(userID, ampli.EventName.Builder().EventProp(true).Build())

The optional EventOptions argument lets you pass Amplitude fields, like DeviceID.

For example, in the following code snippet, your tracking plan contains an event called songPlayed. The event has two required properties: songId and songFavorited. The property type for songId is string, and songFavorited is a boolean.

ampli.Instance.SongPlayed("user_id", ampli.SongPlayed.Builder().
    SongId("songId").
    SongPlayed(true).
    Build(),
    amplitude.EventOptions{}
)

Ampli also generates a builder for each event. Use EventName.Builder() to get the corresponding builder for each event.

ampli.Instance.SongPlayed.Builder().
    SongId("songId").
    SongPlayed(true).
    Build()

Send event objects using the generic Track method.

ampli.Instance.Track("user-id", ampli.SongPlayed.Builder().
    SongId("songId").
    SongPlayed(true).
    Build(),
)

Flush

The Ampli Wrapper queues events and sends them on an interval based on the configuration.

Call Flush() to send any pending events immediately.

ampli.Instance.Flush()

Plugin

Plugins extend Amplitude behavior. For example, plugins can modify event properties (enrichment type) or send to third-party APIs (destination type).

First, define your plugin. Refer to plugin examples.

Add your plugin after you initialize Ampli.

ampli.Instance.Client.Add(myDestinationPlugin)

Ampli CLI

Pull

The pull command downloads the Ampli Wrapper code to your project. Run the pull command from the project root.

ampli pull

Ampli prompts you to log in to your workspace and select a source.

➜ ampli pull
Ampli project is not initialized. No existing `ampli.json` configuration found.
? Create a new Ampli project here? Yes
? Organization: Amplitude
? Workspace: My Workspace
? Source: My Source

Status

Verify that your code implements your events with the status command.

ampli status [--update]

The output shows status and lists missing events.

➜ ampli status
✘ Verifying event tracking implementation in source code
 ✔ Song Played (1 location)
 ✘ Song Stopped Called when a user stops playing a song.
Events Tracked: 1 missed, 2 total