Ambassador Destination

This destination is currently in beta. If you are interested in joining, let us know!

Segment makes it easy to send your data to Ambassador (and lots of other destinations). Once you've tracked your data through our open source libraries we'll translate and route your data to Ambassador in the format they understand. Learn more about how to use Ambassador with Segment.

Segment makes it easy to send your data to Ambassador (and lots of other destinations). Once you’ve tracked your data through our open source libraries we’ll translate and route your data to Ambassador in the format they understand.

Ambassador

Ambassador allows your company to easily create, track & manage custom incentives that drive referrals and evangelize your users. Visit Website

Our Ambassador destination code is open sourced on Github. Feel free to check it out: JS

Getting Started

When you toggle on Ambassador in Segment, this is what happens:

  • Our CDN is updated within 5-10 minutes. Then our snippet will start asynchronously loading Ambassador’s javascript snippet onto your page. This means you should remove Ambassador’s snippet.
  • Since Ambassador only records specific events and user data, events and users may not appear in Ambassador until you start using the API outlined below.

Identify

The first thing you’ll want to do is identify your users so Ambassador knows who they are. You’ll use the identify method to accomplish this.

identify takes the unique userId of a user and a specific set of traits. All supported traits are listed in the example below.

analytics.identify('user1234', {
  email: 'anne@example.com',
  firstName: 'Anne',
  lastName: 'Stein',
  company: 'Ambassador',
  phone: '123-123-1234',
  address: {
    street: '1234 Test Rd.',
    city: 'Wooster',
    state: 'Ohio',
    postalCode: '12345',
    country: 'USA'
  }
})

You can optionally use the URL campaign map to enroll the user as an ambassador. See Mapping campaigns to URLs below for more details

Track

If the event name is mapped to a conversion Ambassador will record this event as a conversion when track is called. You can map analytics.js event names to conversions in your Segment account under the advanced settings for the Ambassador destination.

identify must be called before any conversion events. All supported track properties are listed in the example below:

analytics.track('Checkout Success', {
  orderId: 'order-123'
  revenue: 123.50,
  commissionApproved: true,
  eventData1: 'event 1',
  eventData2: 'event 2',
  eventData3: 'event 3'
})

A campaign is also required in order for a conversion to be recorderd. You may use the campaign mapping below to map campaigns to specific urls.

Mapping campaigns to URLs

Campaigns can be mapped to specific urls for use with identify or track on matching URLs. Follow the instructions below to set up your campaign mapping.

  1. Log into your Segment account and go to the settings for the Ambassador destination.
  2. In the first field add the URL to be mapped. Wildcards can be used to match multiple domains/paths. See URL mapping examples below for more details.
  3. In the second field add the ID of the campaign to be used when the URL matches. You can find campaign IDs in your Ambassador account.
  4. Save changes.

Once set up the campaign ID will be sent with any track or identify calls matching the corresponding url. If the browser URL matches multiple campaigns identify and/or track will be called once per campaign.

URL mapping examples

  • *.*/* - matches any domain and any path.
  • *.example.com - matches root path at any subdomain on example.com.
  • www.*.com - matches any .com domain with at the www subdomain.
  • example.* - matches any domain suffix.
  • example.com/path - matches only example.com/path.
  • example.com/* - matches any path on example.com.
  • example.com/products/* - matches any path after /products.
  • example.com/products/*/refer - matches any path with products in the first path position and refer in the third path position.
  • example.com/#/ - matches only hash root path.
  • example.com/#/* - matches any hash path.
  • example.com/#/products/*- matches any hash path after /products.
  • example.com/#/products/*/refer - matches any hash path with products in the first path position and refer in the third path position.

Example Campaign Map


Supported Sources and Connection Modes

WebMobileServer
📱 Device-based
☁️ Cloud-based

To learn more about about Connection Modes and what dictates which we support, see here.

Settings

Segment lets you change these destination settings via your Segment dashboard without having to touch any code.

Events

A mapping of custom events you’d like to pass through to Ambassador to the corresponding Ambassador event type. For example, if you want to track an Ambassador conversion, add your event name on the left and “conversion” on the right.

Client ID

You can find your Client ID in your Ambassador dashboard by clicking on Editor inside the Build section. On the following page, click the ‘Here you go’ link next to ‘Need the code snippet or credentials?’ and copy the value shown under ID. It should be 32 characters long, and look something like this: 012345ab-c0d1-110e-1f0g-h1234ij5kl6m.

Campaigns

Each campaign runs at a specific url like /share or /invite. Map that url on the left to the Ambassador campaign for that page on the right.


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!