# Analytics for Go v2 (Deprecated) Segment's Go library lets you record analytics data from your Go code. The requests hit Segment's servers, and then are routed your data to any analytics service you enable on your destinations page. This library is open-source, so you can [check it out on GitHub](https://github.com/segmentio/analytics-go). All of Segment's server-side libraries are built for high-performance, so you can use them in your web server controller code. This library uses a tunable buffer to batch messages, optimized for throughput and reduced network activity. ## Getting started ### Install the package Install `analytics-go` using `go get`: ```bash go get github.com/segmentio/analytics-go ``` Then import it and initialize an instance with your source's **Write Key**. Of course, you'll want to replace `YOUR_WRITE_KEY` with your actual **Write Key** which you can find in Segment under your source settings. ```go package main import "github.com/segmentio/analytics-go" func main() { client := analytics.New("YOUR_WRITE_KEY") } ``` That will create a `client` that you can use to send data to Segment for your source. The default initialization settings are production-ready and queue 20 messages before sending a batch request, and send batch requests on a 5 second interval. ## Identify Identify lets you tie a user to their actions and record traits about them. It includes a unique User ID and any optional traits you know about them. Segment recommends calling Identify a single time when the user's account is first created, and only identifying again later when their traits change. Example Identify call: ```go client.Identify(&analytics.Identify{ UserId: "019mr8mf4r", Traits: map[string]interface{}{ "name": "Michael Bolton", "email": "mbolton@example.com", "plan": "Enterprise", "friends": 42, }, }) ``` This call is identifying Michael by his unique User ID (the one you know him by in your database) and label him with `name`, `email`, `plan` and `friends` traits. An Identity call has the following fields: | Field | Data type | Description | | --------- | ------------------------- | ---------------------------------------------------------- | | `message` | *map\[string]interface{}* | Identify message. A `userId` or `anonymousId` is required. | Find details on the Identify method payload in the [Segment Spec](/docs/segment/connections/spec/identify/). ## Track Track lets you record the actions your users perform. Every action triggers an event, which can also have associated properties. You'll want to track events that are indicators of success for your site, like **Signed Up**, **Item Purchased** or **Article Bookmarked**. To get started, Segment recommends tracking just a few important events. You can always add more later. Example Track call: ```go client.Track(&analytics.Track{ Event: "Signed Up", UserId: "f4ca124298", Properties: map[string]interface{}{ "plan": "Enterprise", }, }) ``` This example Track call tells us that your user just triggered the **Signed Up** event choosing the "Enterprise" plan. Track event properties can be anything you want to record. In this case, plan type. The Track call has the following fields: | Field | Data type | Description | | --------- | ------------------------- | ------------------------------------------------------- | | `message` | *map\[string]interface{}* | Track message. A `userId` or `anonymousId` is required. | Find details on best practices in event naming and the Track method payload in the [Segment Spec](/docs/segment/connections/spec/track/). ## Page The [Page](/docs/segment/connections/spec/page/) method lets you record page views on your website, along with optional extra information about the page being viewed. If you're using Segment's client-side set up in combination with the Go library, Page calls are already tracked for you by default. However, if you want to record your own page views manually and aren't using our client-side library, read on! Example Page call: ```go client.Page(&analytics.Page{ UserId: "f4ca124298", Category: "Docs", Name: "Go library", Traits: map[string]interface{}{"url": "https://segment.com/libraries/go/"}, }) ``` A Page call has the following fields: | Field | Data type | Description | | ------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `UserId` | *string* | The ID for this user in your database. | | `Category` | *string, optional* | The category of the page. Useful for things like ecommerce where many pages often live under a larger category. | | `Name` | *string, optional* | The name of the of the page, for example **Signup** or **Home**. | | `Traits` | *map\[string]interface{}, optional* | A few traits about the page that are specially recognized and automatically translated: `url`, `title`, `referrer` and `path`, but you can add your own too. | | `Timestamp` | *string, optional* | If the track just happened, leave it out and Segment will use the server's time. If you're importing data from the past make sure you to send a `timestamp`. Timestamp should be in [ISO8601](http://www.iso.org/iso/home/standards/iso8601.htm) form. | | `Context` | *map\[string]interface{}, optional* | Extra context to attach to the call. **Note:** `context` differs from `traits` because it is not attributes of the user itself. | | `AnonymousId` | *string, optional* | An ID to associated with the user when you don't know who they are (for example, [the anonymousId generated by `analytics.js`](/docs/segment/connections/sources/catalog/libraries/website/javascript/#anonymous-id)) | Find details on the Page payload the [Segment Spec](/docs/segment/connections/spec/page/). ## Group Group lets you associate an [identified user](/docs/segment/connections/sources/catalog/libraries/server/node/#identify) with a group. A group could be a company, organization, account, project or team. The Group call also lets you record custom traits about the group, like industry or number of employees. This is useful for tools like [Intercom](/docs/segment/connections/destinations/catalog/intercom/), [Preact](/docs/segment/connections/destinations/catalog/preact/) and [Totango](/docs/segment/connections/destinations/catalog/totango/), as it ties the user to a **group** of other users. Example Group call: ```go client.Group(&analytics.Group{ UserId: "019mr8mf4r", GroupId: "56", Traits: map[string]interface{}{ "name": "Initech", "description": "Accounting Software", }, }) ``` A Group call has the following fields: | Field | Data type | Description | | --------- | ------------------------- | ------------------------------------------------------------------------- | | `message` | *map\[string]interface{}* | Group message. An `event` name and `userId` or `anonymousId` is required. | Find more details about Group calls, including the \*Group payload, in the [Segment Spec](/docs/segment/connections/spec/group/). ## Alias Alias is how you associate one identity with another. This is an advanced method, but it is required to manage user identities successfully in *some* of our destinations. In [Mixpanel](/docs/segment/connections/destinations/catalog/mixpanel/#alias) it's used to associate an anonymous user with an identified user once they sign up. For [Kissmetrics](/docs/segment/connections/destinations/catalog/kissmetrics/#alias), if your user switches IDs, you can use 'alias' to rename the 'userId'. Example Alias call: ```go client.Alias(&analytics.Alias{ PreviousId: anonymousUser, UserId: "019mr8mf4r", }) ``` The Alias call has the following fields: | Field | Data type | Description | | ------------ | --------- | -------------------------------------- | | `UserId` | *string* | The ID for this user in your database. | | `PreviousId` | *string* | The previous ID to alias from. | Here's a full example of how you might use the Alias call: ```go // the anonymous user does actions ... client.Track(&analytics.Track{ Event: "Anonymous Event", UserId: anonymousUser, }) // the anonymous user signs up and is aliased client.Alias(&analytics.Alias{ PreviousId: anonymousUser, UserId: "019mr8mf4r", }) // the identified user is identified client.Identify(&analytics.Identify{ UserId: "019mr8mf4r", Traits: map[string]interface{}{ "name": "Michael Bolton", "email": "mbolton@example.com", "plan": "Enterprise", "friends": 42, }, }) // the identified user does actions ... client.Track(&analytics.Track{ Event: "Item Viewed", UserId: "019mr8mf4r", Properties: map[string]interface{}{ "item": "lamp", }, }) ``` For more details about Alias, including the Alias call payload, check out the [Segment Spec](/docs/segment/connections/spec/alias/). ## Development settings You can use the `Size` field set to 1 during development to make the library flush every time a message is submitted so that you can be sure your calls are working properly. ```go func main() { client := analytics.New("YOUR_WRITE_KEY") client.Size = 1 } ``` ## Logging The `DEBUG` environment variable can be used to enable logging during runtime, like so: ```text DEBUG=analytics go run test.go ``` ## Selecting destinations The Alias, Group, Identify, Page, and Track calls can all be passed an object of `context.integrations` that lets you turn certain integrations on or off. By default, all destinations are enabled. Here's an example Track call with the `context.integrations` object shown. ```go client.Track(&analytics.Track{ Event: "Membership Upgraded", UserId: "019mr8mf4r", Integrations: map[string]interface{}{ "All": false, "Mixpanel": true, }, }) ``` In this case, we're specifying that we want this Track to only go to Vero. `All: false` says that no destination should be enabled unless otherwise specified. However, setting an integration to true (for example,`Vero: true`) means you want events to flow to that individual destination. Destination flags are **case sensitive** and match [the destination's name in the docs](/docs/segment/connections/destinations/) (for example, "AdLearn Open Platform", "awe.sm", "MailChimp", etc.). **Note**: * Available at the business level, filtering track calls can be done right from the Segment UI on your source schema page. We recommend using the UI if possible since it's a much simpler way of managing your filters and can be updated with no code changes on your side. * If you are on a grandfathered plan, events sent server-side that are filtered through the Segment dashboard will still count towards your API usage. ## Historical import You can import historical data by adding the `timestamp` argument to any of your method calls. This can be helpful if you've just switched to Segment. Historical imports can only be done into destinations that can accept historical timestamped data. Most analytics tools like Mixpanel, Amplitude, and Kissmetrics can handle that type of data just fine. One common destination that does not accept historical data is Google Analytics since their API cannot accept historical data. **Note**: If you're tracking things that are happening right now, leave out the `timestamp` and our servers will timestamp the requests for you. ## Batching Segment's libraries are built to support high performance environments. That means it is safe to use analytics-go on a web server that's serving hundreds of requests per second. Every method you call **does not** result in an HTTP request, but is queued in memory instead. Messages are flushed in batch in the background, which allows for much faster operation. By default, the Analytics-Go library will flush: * Every 20 messages (control with `FlushAt`) * If 5 seconds has passed since the last flush (control with `FlushAfter`) There is a maximum of `500KB` per batch request and `32KB` per call. > \[!WARNING] > > Segment's HTTP Tracking API accepts batch requests up to **500 KB**. To avoid errors in event creation, ensure that individual event payload sizes remain below **32 KB**. Sometimes you might not want batching (when debugging, or in short-lived programs for example). You can turn off batching by setting the `FlushAt` argument to `1`, and your requests will always be sent right away. ## Options You can configure analytics-go with the following fields: | Field. | Data type | Description | | ---------- | --------- | -------------------------------------------------------------- | | `Size` | *int* | The number of messages to queue before flushing. | | `Endpoint` | *string* | The endpoint that Segment should use to send your requests to. | ## Troubleshooting The following tips often help resolve common issues. ### No events in my debugger 1. Double check that you've followed all the steps in the [Quickstart](quickstart/). 2. Make sure that you're calling a Segment API method once the library is successfully installed—[`identify`](#identify), [`track`](#track), etc. 3. Make sure your application isn't shutting down before the `Analytics.Client` local queue events are pushed to Segment. You can manually call `Analytics.Client.Flush()` to ensure the queue is fully processed before shutdown. ### Other common errors If you are experiencing data loss from your source, you may be experiencing one or more of the following common errors: * **Payload is too large**: If you attempt to send events larger than 32KB per normal API request or batches of events larger than 500KB per request, Segment's tracking API responds with `400 Bad Request`. Try sending smaller events (or smaller batches) to correct this error. * **Identifier is not present**: Segment's tracking API requires that each payload has a `userId` and/or `anonymousId`. If you send events without either the `userId` or `anonymousId`, Segment's tracking API responds with an `no_user_anon_id` error. Check the event payload and client instrumentation for more details. * **Track event is missing name**: All Track events to Segment must have a name in string format. * **Event dropped during deduplication**: Segment automatically adds a `messageId` field to all payloads and uses this value to deduplicate events. If you're manually setting a `messageId` value, ensure that each event has a unique value. * **Incorrect credentials**: Double check your credentials for your downstream destination(s). * **Destination incompatibility**: Make sure that the destination you are troubleshooting can accept server-side API calls. You can see compatibility information on the [Destination comparison by category](/docs/segment/connections/destinations/category-compare/) page and in the documentation for your specific destination. * **Destination-specific requirements**: Check out the [destination's documentation](/docs/segment/connections/destinations/) to see if there are other requirements for using the method and destination that you're trying to get working.