Enable with Segment

The Enable with Segment Button is a fast and easy way for new customers to start sending data to your app, as soon as they sign up. If you’ve already integrated with Segment as a partner, you can implement the button in your setup-flow now. If you haven’t integrated with us yet, you can learn more about joining our platform here.

Without the Segment button, a customer who wants to activate your product via Segment would need to visit the Segment website, choose a project to send data from, go to the Segment dashboard, find your service amongst hundreds of other destinations and copy-paste API keys from your interface. We saw that many users were confused going through this process! This explainer video will show a customer’s current confusion, and what an experience would look like with the new button.

The Enable with Segment Button will improve your activation rate with Segment customers because it simplifies the activation process.

Example Flow

Enable with Segment Destination Flow

Install the Button

Implementing the Segment button and improving your activation experience is easy.

The bare minimum to get the button functional is to include your “Integration ID” as well as the settings we will use to configure the destination. Since both of these rely on Segment internals, below is a little tool to help you discover those values.

Add HTML

<script src="//static.segment.com/enable-button/v1/index.js" async></script>

<div class="segment-enable-button"
     data-integration="..."
     data-settings="..."></div>

Add Settings

KeyNameType
Select your app above to show available settings

The settings can vary a lot from destination to destination, so in order to give you the most flexibility, we’ve opted to use a raw JSON string for this attribute. (for example: data-settings='{"apiKey":"abc123"}')

When you choose your destination above, we will give you a list of all the settings we offer to our customers to configure their destination. (required settings will be in bold) Your JSON object can use any of the keys specified above.

Available Options

Integration ID (data-integration)

The Integration ID will let us know which destination your user is interested in activating. Select your app from the dropdown in the Install the Button section to make sure you know what your Integration ID is. Set your Integration ID in the data-integration attribute on the button element.

data-integration="my-app"

Settings (data-settings)

In order for a customer to successfully send data from their Segment data hub to your app, we’ll need the proper configuration for your customer. Select your app from the dropdown in the Install the Button section to make sure you know what configuration options are available for your destination. The settings will need to be encoded as a raw JSON string in the data-settings attribute.

data-settings='{"apiKey":"..."}'

Redirect URL (data-redirect-url)

The redirect URL can be anything you want it to be. It’s where we’ll send customers after successfully starting the flow of data from Segment to your app. This could be a page for further setup and activation, or a dashboard where they’ll be able to start seeing data.

data-redirect-url="http://example.com/"

Note that if a redirect URL is not specified, we will simply bring the user to the configuration page inside our own app so that they can setup Segment on their site, servers, or app. Similarly, if the user has not started sending data via Segment, we will ignore your redirect url so that the customer can setup Segment. This prevents confusion about why Segment or the destination isn’t working.

Button Size (data-size)

The button has one visual style but can be easily displayed in three different sizes: large, small and medium (the default). Set the size of your Segment Activation button via the data-size attribute.

<!-- large button -->
data-size="large"

<!-- small button -->
data-size="small"

Advanced Usage

If you need more flexibility, you can also use the raw JS API for the button. When the script above is loaded, it will create a segment global namespace.

When the script loads, it will automatically initialize the button for any .segment-enable-button elements it finds on the page. If you don’t necessarily have your button ready on page load, you can also trigger this magic yourself using segment.EnableButton.init().

Otherwise, you can initialize new buttons yourself using segment.EnableButton as a constructor:

var btn = new segment.EnableButton({
  element: '#my-button',
  integration: '...',
  settings: {}
});

Available Configuration Options:

Most of the configuration options below correspond to the HTML options above, except being in camelCase instead of being hyphenated.

KeyTypeComments
elementString, HTMLElementRequired: A CSS selector string (for a single element) or the raw DOM node itself.
integrationStringRequired: The Integration ID, see above
settingsObject, FunctionRequired: Can either be a raw JS object or a function that returns an object. (see below)
redirectUrlStringSee above
sizeStringSee above

Generating Settings with a Function

In some cases, it might not be possible to know the settings ahead of time. In this case, we’ve allowed for settings to be passed as a function, which will be invoked when the user clicks the button, but before they are taken to Segment:

var btn = new segment.EnableButton({
  element: '#my-button',
  integration: '...',
  settings: function() {
    return { /* ... */ };
  }
});

You can also work asynchronously, simply add an argument to your function. This will be passed in as a callback function. (it only accepts a single argument, which is the settings object you’ve generated)

var btn = new segment.EnableButton({
  element: '#my-button',
  integration: '...',
  settings: function(done) {
    generateKey(function(err, key) {
      // make sure to handle errors yourself, as the button has no error-handling
      done({ apiKey: key });
    });
  }
});

When using a function, errors will need to be handled directly by your application.

Examples of Button Placement

Kissmetrics Kissmetrics

Threads Threads


If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!