Ambassador Destination

Destination Info
Connection Modes
Device-mode Cloud-mode
Web Web
Mobile Mobile
Server Server

Ambassador empowers companies to easily create, track & manage custom incentives that drive referrals and evangelize their users.

Getting Started

Before you start, make sure Ambassador supports the source type and connection mode you’ve chosen to implement. You can learn more about connection modes here.

Web Mobile Server
📱 Device-mode ⬜️ ⬜️
☁️ Cloud-mode ⬜️ ⬜️ ⬜️
  1. From the Segment web app, click Catalog.
  2. Search for “Ambassador” in the Catalog, select it, and choose which of your sources to connect the destination to.
  3. In the destination settings, enter your “Client ID” from your Ambassador dashboard, and populate any “Campaigns” to be mapped as per the below Mapping campaigns to URLs section.

Your changes appear in the Segment CDN in about 45 minutes, and then Analytics.js starts asynchronously loading the Ambassador snippet on your page and sending data.

Since Ambassador only records specific events and user data, events and users may not appear in Ambassador until you start using the API explained below. And you must approve your website domain through the Editor -> Manage websites section in the navigation pane along the left-hand side of the page.


If you’re not familiar with the Segment Specs, take a look to understand what the Identify method does.

For Ambassador it 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: '',
  firstName: 'Anne',
  lastName: 'Stein',
  company: 'Ambassador',
  phone: '123-555-1234',
  address: {
    street: '1234 Test Rd.',
    city: 'Wooster',
    state: 'Ohio',
    postalCode: '12345',
    country: 'USA'

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


If you’re not familiar with the Segment Specs, take a look to understand what the Track method does.

For Ambassador track events will be recorded as a conversion if the Segment event name is mapped to a campaign in your Ambassador destination settings in the Segment UI. All supported 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'

NOTE: identify must be called before any conversion events.


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 as detailed in the URL mapping examples below.
  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 identify or track 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
  • * - matches root path at any subdomain on
  • www.*.com - matches any .com domain with at the www subdomain
  • example.* - matches any domain suffix
  • - matches only
  •* - matches any path on
  •* - matches any path after /products
  •*/refer - matches any path with products in the first path position and refer in the third path position
  • - matches only hash root path
  •* - matches any hash path
  •*- matches any hash path after /products
  •*/refer - matches any hash path with products in the first path position and refer in the third path position


Segment lets you change these destination settings from the Segment app without having to touch any code.

Setting Description
text-map, defaults to {}.

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.
Events text-map, defaults to {}.

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
string. You can find your Client ID in your Ambassador dashboard by clicking on Editor in the navigation pane along the left-hand side of the page. 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.

This page was last modified: 03 May 2022

Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
Create free account