Segment for Developers

This guide explains all you need to know to get started with your Segment implementation, and directs you to more resources depending on your specific needs.

What does Segment do?

Segment sends messages about activities in your mobile apps, websites or servers, receives those messages, and translates and forwards the message content to Destination tools. It also can send the contents of those messages to a bulk storage destination for archiving. In more complicated implementations, Segment can serve as a wrapper to trigger messages directly to other APIs, and can inspect, correct, classify and block the message contents.

Types of Segment messages

Segment’s libraries generate and send messages to our tracking API in JSON format, and provide a standard structure for the basic API calls. We also provide recommended JSON structure (also known as a schema, or ‘Spec’) that helps keep the most important parts of your data consistent, while allowing great flexibility in what other information you collect and where.

There are six calls in the basic tracking API, which answer specific questions:

• Identify: Who is the user?
• Track: What are they doing?
• Page: What web page are they on?
• Screen: What app screen are they on?
• Group: What account or organization are they part of?
• Alias: What was their past identity?

Among these calls, you can think of Identify, Group, and Alias as similar types of calls, all to do with updating our understanding of the user who is triggering Segment messages. You can think of these calls as adding information to, or updating an object record in a database. Objects are described using “traits”, which you can collect as part of your calls.

The other three, Track, Page, and Screen, can be considered as increasingly specific types of events. Events can occur multiple times, but generate separate records which append to a list, instead of being updated over time.

A Track call is the most basic type of call, and can represent any type of event. Page and Screen are similar and are triggered by a user viewing a page or screen, however Page calls can come from both web and mobile-web views, while Screen calls only occur on mobile devices. Because of the difference in platform, the context information collected is very different between the two types of calls.

Anatomy of a Segment message

The most basic Segment message requires only a userID or anonymousID; all other fields are optional to allow for maximum flexibility. However, a normal Segment message has three main parts: the common fields, the “context” object, and the properties (if it’s an event) or traits (if it’s an object).

The common fields include information specific to how the call was generated, like the timestamp and library name and version. The fields in the context object are usually generated by the library, and include information about the environment in which the call was generated: page path, user agent, OS, locale settings, etc. The properties and traits are optional and are where you customize the information you want to collect for your implementation.

Another common part of a Segment message is the integrations object, which you can use to explicitly filter which destinations the call is forwarded to. However this object is optional, and is often omitted in favor of non-code based filtering options.

Message schemas, Blocks, and Specs

The Segment “Specs” provide recommended message schemas - the information we recommend that you collect - for each type of call. These are recommendations not requirements, but if you follow these schema guidelines the Segment servers can more easily identify parts of your messages, and translate them to downstream tools.

In addition to the recommended message schemas, Segment also provides “blocks”: recommendations on what information to collect and how to format it, for different industries and use cases. These are recommendations only, but by collecting all of the information in these blocks, you can ensure that common tools used in that use-case have the information they need to function.

A third section of the Spec is the “industry specs” which provide recommendations that include an explicit translation or mapping in the Segment servers, to best power the downstream Destinations commonly used in these industries.

Sources and Destinations

When you start out, you create a Workspace, which serves as a container for all of your Sources and Destinations.

Segment has Sources and Destinations. Sources send data into Segment, while Destinations receive data from Segment.

Segment has five types of sources: Web (Analytics.js), Mobile, Server, and Cloud App, plus a fifth type: User-created Source Functions. Web, Mobile, and Server sources send first-party data from your digital properties. Cloud-app sources send data about your users from your connected web apps, for example a ticketing system such as Zendesk, a payments system such as Stripe, or a marketing tool like Braze.

Connection modes

Segment has several types of sources, and many destinations can accept data from all of them. However, some are only compatible with specific source types (for example, web only, or server only). To find out which source types a specific destination can accept data from, check the documentation for that destination for a “Supported Sources and Connection Modes” section.

Segment’s web source (Analytics.js), and native client-side libraries (iOS, Android, React-native) allow you to choose how you send data to Segment from your website or app. There are two ways to send data:

• Cloud-mode: The sources send data directly to the Segment servers, which then translate it for each connected downstream destination, and send it on. Translation is done on the Segment servers, keeping your page size, method count, and load time small.

  Healthcare and Life Sciences (HLS) customers can encrypt data flowing into their destinations

  HLS customers with a HIPAA eligible workspace can encrypt data in fields marked as Yellow in the Privacy Portal before they flow into an event stream, cloud-mode destination.
  To learn more about data encryption, see the HIPAA Eligible Segment documentation

• Device-mode: You include additional code on your website or mobile app which allows Segment to use the data you collect on the device to make calls directly to the destination tool’s API, without sending it to the Segment servers first. (You still send your data to the Segment servers, but this occurs asynchronously.) This is also called wrapping or bundling, and it might be required when the source has to be loaded on the page to work, or loaded directly on the device to function correctly. When you use Analytics.js, you can change the device-mode destinations that a specific source sends from within the Segment web app, without touching any code.

To learn more about connection modes and when you should use each, see the details in the Destinations docs.

Planning your Segment implementation

The journey of a thousand miles begins, ideally, with a plan. Regardless of if you’re a new company just implementing analytics for the first time, or a multi–national corporation modernizing your analytics stack, it’s a great idea to start with a Tracking Plan. For new implementations, this can be as simple as a document where you write down these four things for each item you track:

• What am I tracking? (What is the event name or type?)
• Why am I tracking it? (What questions does this data answer?)
• For whom am I tracking it? (Who owns this question, tool, or business area?)
• Where (which destination tools) do I want to send this data to?

If you’re a large or long-established organization and you’re replacing existing tools, you’ll want to spend more time on this to maintain analytic parity and continuity of tooling. We highly recommend reading up on tracking plans and schemas for Protocols, our tool for managing and sharing tracking plans and enforcing schemas.

Regardless of your organization’s size or age, you’ll want to take an inventory of the destination tools you’ll be using with Segment, and make a list of the connection modes each one accepts. This makes it easier to check off when you’ve implemented each one, so you’re not missing anything.

How do I test if it’s working?

There are several ways to check if your data is flowing. One is the Debugger tab in each Source in the Segment web app, where you can see data coming from a source into Segment. Another is the Event Delivery tool which shows which data is arriving at specific destinations.

For monitoring purposes, you’ll also see alerts in the Workspace Health tool if your sources or destinations produce repeated errors.

How do I filter my data?

There are several different ways to ensure that you can collect your data once, but filter it out of specific destinations. See Filtering Data for a list of the available methods and descriptions.

Troubleshooting

If you’re seeing errors thrown by your destinations, you might have an implementation issue. See the Integration Error Codes list or contact our Success engineering team for help.

Segment Terraform Provider

Segment has a Terraform provider, powered by the Public API, that you can use to manage Segment resources, automate cloud deployments, and change control. Take a look at the Segment provider documentation on Terraform to see what’s supported.