Sending Segment Data to Destinations

You’ve decided how to format your data, and collected it using Segment Sources. Now what do you do with it? You send the data to Destinations.

Destinations are tools or services which can use the data sent from Segment to power analytics, marketing, customer outreach, and more.

Adding a destination

There are two ways to add a destination to your deployment: using the Segment web app, or using the Public API.

Adding a destination from the Segment web app

1. Before you start, log in to your account on the destination tool, and get the token or other credentials needed to access the tool. You’ll use these to give Segment permission to send data to the tool.
2. Log in to the Segment web app, and select the workspace you want to add the destination to.
3. Click Catalog in the left navigation, and click the Destinations tab.
4. Search for the destination you want to add, and click it in the results. If there are multiple results for your search, you can click each result to read more about them until you find the one you’re looking for.
5. In the panel that appears, click Configure.
6. On the next page, select a source to connect to the destination, and click Confirm Source.
7. On the next page, find the Connection Settings section, and enter the token or credentials for that destination tool.
8. Click the toggle at the top of the Settings page to enable the destination.

Adding a destination to a specific Segment Source

You can also add a destination directly from the source’s settings page in the Segment web app.

1. Before you start, log in to your account on the destination tool, and get the token or other credentials needed to access the tool. You’ll use these to give Segment permission to send data to the tool.
2. Log in to the Segment web app, and select the workspace you want to work in, and navigate to the source you want to add the destination to.
3. From the source information page, click Add Destination.
4. Search for the destination you want to add, and click it in the results. If there are multiple results for your search, you can click each result to read more about them until you find the one you’re looking for.
5. In the panel that appears, click Configure.
6. On the next page, find the Connection Settings section, and enter the token or credentials for that destination tool.
7. Click the toggle at the top of the Settings page to enable the destination.

Adding a destination using the Public API

You can use the Segment Public API to add destinations to your workspace using the Create Destination endpoint. The API requires an authorization token, and uses the name field as a namespace that defines which source the destination is connected to. You send the rest of the destination’s configuration as a JSON blob. View the documentation page in the Segment Catalog, or query the Segment Catalog API, for a destination to see the available settings.

What happens when you add a destination

Adding a destination can have a few different effects, depending on which sources you set up to collect your data, and how you configured them.

Analytics.js

If you are using Segment’s JavaScript library, Analytics.js, then Segment handles any configuration changes you need for you. If you’re using Analytics.js in cloud-mode, the library sends its tracking data to the Segment servers, which route it to your destinations. When you change which destinations you send data to, the Segment servers automatically add that destination to the distribution list.

If you’re using Analytics.js in device-mode, then Analytics.js serves as a wrapper around additional code used by the individual destinations to run on the user’s device. When you add a destination, the Segment servers update a list of destinations that the library queries. When a user next loads your site, Analytics.js checks the list of destinations to load code for, and adds the new destination’s code to what it loads. It can take up to 30 minutes for the list to update, due to CDN caching.

You can enable device-mode for some destinations from the destination’s Settings page in the Segment web app. You don’t need to use the same mode for all destinations in a workspace; some can use device-mode, and some can use cloud-mode.

Mobile sources

By default, Segment’s mobile sources send data to Segment in cloud-mode to help minimize the size of your apps. In cloud-mode the mobile source libraries forward the tracking data to the Segment servers, which route the data to the destinations. Since the Segment servers know which destinations you’re using, you don’t need to take any action to add destinations to mobile apps using cloud-mode.

However, if the destination you’re adding has features that run on the user’s device, you might need to update the app to package that destination’s SDK with the library. Some destinations require that you package the SDK, and some only offer it

Server sources

Segment’s server sources run on your internal app code, and never have access to the user’s device. They run in cloud-mode only, and forward their tracking calls to the Segment servers, which forward the data to any destinations you enabled.

Destination authentication

When you add a destination in Segment, you must tell Segment how to connect with that destination’s app or endpoints. Most destinations offer an API token or authentication code which you can get from their web app. The documentation for each Segment destination includes information about what you need, and how to find it. Copy this information, and paste it into the Settings for the destination, or include it in the create API call.

Destination settings

Each destination can also have destination settings. These control how Segment transforms the data you send to the destination, and can be used to adapt it to your configuration or enable or disable certain destination features.

Connecting one source to multiple instances of a destination

Segment allows you to connect a source to multiple instances of a destination. You can use this to set up a single Segment source that sends data into different instances of your analytics and other tools.

For example, you might set up a single Segment source to send data both to separate instances of Google Analytics for each business unit in your organization, and to another instance for executive-level reporting. You could also use this to make sure that tooling instances for different geographic teams are populated with the same data from the same source.

You can also connect multiple instances of a destination to help you smoothly migrate from one configuration to another. By sending each version the same data, you can check and validate the new configuration without interrupting use of the old one.

Connect a source to more than one instance of a destination

To connect a source to more than one instance of a destination in the Segment web app, start by adding the first instance of the destination and giving it a unique name, as described above. To add another instance of the destination, follow either of those two methods and choose another unique name.

You must give each instance of the destination connected to the same source a unique name. Segment recommends that you use descriptive names rather than numbers, so other Segment users can understand which Segment destinations are linked to which tool instances. For example, you might use “Amplitude North America” and “Amplitude South America”, instead of “Amplitude 1” and “Amplitude 2”. You can edit the destination instance name at any time.

If you added the first instance of your destination before multi-instance destinations became available, that instance is automatically named for the destination with no other identifiers, for example “Amplitude”.

Some destinations do not support having multiple instances connected to the same source. In that case, the option to add a second instance of that destination does not appear.

You can create unique destination filters for each destination instance connected to the same source.

Connect multiple sources to one instance of a destination

It is not possible to connect multiple instances of one source (for example, two website sources) to the same destination. However, you can create another instance of the destination for the other sources, and click Copy Settings From Other Destination to save yourself time entering the settings values again.

Connect to more than one instance of a destination using the Public API

You can add multiple instances of a destination using the Segment Public API. See the Segment Config API documentation. If a destination does not support multi-instance, the Public API throws an appropriate error.

Multi-instance destinations and Device-mode

• You can connect a source to up to 25 instances of a destination if all of the instances use cloud-mode. Destinations using cloud-mode receive data directly from the Segment servers.
• Mobile sources, and the legacy Project source, can connect to multiple instances of destinations that operate only in cloud-mode. Mobile and Project sources cannot connect to multiple instances of destinations that operate in both cloud-mode and device-mode.
  • Warning: If you bundle one instance of a destination in a mobile source but have other instances of that destination connected to that source you might see unexpected and inconsistent data.
• Non-mobile sources can only connect to one device-mode instance of a destination, in addition to up to 25 cloud-mode instances. A web browser sending to a destination in device-mode sends data directly from the user’s browser (instead of through the Segment servers), by bundling a copy of destination’s code with the Segment SDK. Segment can’t bundle multiple copies of the destination SDK and so it can’t send data to multiple instances of the destination from the browser.
• You cannot connect a source to more than one instance of a destination that operates in device-mode only. These destinations can only accept data from code directly on the user’s device, and Segment cannot include duplicates of that code for a single source.
• Multi-instance support is not available for most hybrid Actions destinations, and will not support Web Mode Actions destinations. Hybrid destinations are those that have some components that operate in device-mode and some that operate in cloud-mode. Actions destinations currently affected by this are Amplitude Actions and Braze Cloud Actions.
  • Amplitude Actions does have multi-instance support for Analytics.js and server sources, but does not have multi-instance support for mobile sources.
  • Braze Cloud Actions does not have multi-instance support because it includes a device-mode web plugin for the Debounce Middleware.

Other multi-instance destination considerations

• Multiple Data Lakes: Segment does not currently support connecting a single source to multiple instances of a data lakes destination. Contact Segment Customer Success if this would be useful for your organization.

• Protocols transformations and multi-instance support: Protocols transformations are specific to each source, and operate the same on all instances of a specific destination. Segment does not currently support creating unique protocols transformations for each instance of a destination.

• Integrations object considerations: A common part of a Segment message is the integrations object, which you can use to explicitly filter to which destinations the call is forwarded, as well as to specify options for different destination tools. If you use the integrations object to filter events or to send destination-specific options, Segment applies its values to all instances. For example:

{
  "integrations": {
    "Mixpanel": false,
    "Adobe Analytics": {
      "marketingCloudVisitorId": "12345"
    }
  }
}

In this example:

• Events sent with this Mixpanel setting are not sent to instances of Mixpanel.
• Events sent to any Adobe Analytics destinations with this Adobe Analytics setting use the same marketingCloudVisitorId value specified. You can not use the integrations object to send data to individual destination instances.