Overview

Vitally's Segment integration can be used to sync the following Segment data into Vitally in real time:

• ​Groups - Vitally imports your Segment groups into Vitally as accounts. The entire group object, including all your Segment traits, will be attached to your Vitally account profiles.

• ​Users - Vitally imports your Segment users (i.e. your identify API calls) into Vitally as users. The entire user object, including all your Segment traits, will be attached to your Vitally user profiles.

• ​Tracks - Vitally imports your Segment tracks into Vitally as product events. The entire track object, including any event properties, will be imported.

Unlinking a user from an account in Vitally

You can disassociate a user from a company by passing in a field inside the company trait with remove: true in your identify calls.

analytics.identify({
  userId: '1',
  traits: {
    company: {
      id: 12345,
      remove: true
    }
  }
});

Enabling the Segment integration

To enable the Segment integration, navigate to Integrations -> Segment in your Account Settings (get there via Quick Jump). When there, simply click the Connect a Segment Source button. That will redirect you to Segment, where you'll be able to select the Segment source to connect to Vitally.

Once your source is submitted, Segment will redirect you back to Vitally, where you'll likely see a message like this:

Before you can complete the Segment integration process in Vitally, we must receive at least 1 Segment message from your connected source. This can take a few minutes after you connect your source, even if you know messages are being sent. This occurs because Segment's CDN needs to propagate your new connection throughout its infrastructure before they route your messages to Vitally. That propagation can take several minutes to complete.

Once we receive a single Segment message, you'll see the below and will be able to configure the rest of the integration.

Creating accounts from Segment

As Vitally is geared towards B2B companies, we must be able to associate each user to the account/customer they belong to. Segment provides 2 different APIs to achieve this result.

Option #1: Group API (recommended)

Option #2: Identify API

Option #1: Group API (recommended)

This is a dedicated API Segment provides that directly identifies an account. A sample group API call made using Segment's Javascript SDK would look something like this:

analytics.group("0e8c78ea9d97a7b8185e8632", {
  name: "Initech",
  industry: "Technology",
  employees: 329,
  plan: "enterprise", 
  totalBilled: 830
});

If you use the Group API, then the only other requirement is to ensure your Group API calls have a name trait attached to them.

Using the Group API to create accounts is strongly recommended. This API is your best option for creating accounts in Vitally, as it allows you to directly define your account data in Vitally. For example, the sample API call above would provide access to the industry, employees, plan, and totalBilled traits for the account in Vitally. Additionally, any future traits your engineers add to a group API call will be automatically attached to your accounts in Vitally.

Option #2: Identify API

This is a dedicated API Segment provides that directly identifies your users. Since this API is meant to identify individual users of your product, and not necessarily the account the user belongs to, it is not recommended to use this API. The Group API is always a better option, but if you don't use the Group API, your Identify API calls must send along certain traits that specify the account.

• Account name trait - A trait that identifies the (readable) name of the account the user belongs to (e.g. "Visa")

• Account ID trait - A trait that specifies a unique ID for your accounts. Ideally, this value never changes for the account (e.g. "visa.com", "ed8fcc72-dbe5-4a9c-9d03-59e456462626"). This trait should pretty much always be different than yournametrait. If at all possible, the trait you select here should be the unique ID given to your accounts by your database.

• Other account traits - Any traits attached to Identify API calls that actually relate to the account the user belongs to (e.g. the account's plan, subscription cost, industry). These traits will be attached to accounts in Vitally, allowing you to use them when analyzing accounts.

The Account ID trait you select here is very important to unifying your account data in Vitally. If you leverage our other integrations to track other customer data (e.g. Stripe), the ID you select here will also need to exist in those other tools in order for Vitally to properly unify your data under the right account.

FAQs

Does my historical Segment data sync to Vitally when I enable the Segment integration? Unfortunately not, but simply because Segment offers no APIs for integration partners to extract your historical data from Segment. However, for those on advanced plan tiers for Segment, Segment does offer a feature to "replay" your historical data to a connected destination. If you have access to that feature, you can use it to push your historical data from Segment to Vitally.