Ambassador Destination

Ambassador empowers companies to easily create, track & manage custom incentives that drive referrals and evangelize their users. The Ambassador Destination is open-source. You can browse the code on GitHub.

This document was last updated on September 03, 2018. If you notice any gaps, outdated information or simply want to leave some feedback to help us improve our documentation, please let us know!

Getting Started

The first step is to make sure Ambassador supports the source type and connection mode you’ve chosen to implement. You can learn more about what dictates the connection modes we support here.

WebMobileServer
📱 Device-based
☁️ Cloud-based
  1. From your Segment UI’s Destinations page click on “Add Destination”.
  2. Search for “Ambassador” within the Destinations Catalog and confirm the Source you’d like to connect to.
  3. Drop in your “Client ID” from your Ambassador dashboard, and populate any “Campaigns” to be mapped as per the below Mapping campaigns to URLs section.
  4. In about 5-10 minutes the CDN will be updated and the Ambassador snippet will be initialized onto your page.
  5. 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

If you haven’t had a chance to review our spec, please 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: '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'
  }
})

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.

Track

If you haven’t had a chance to review our spec, please 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.

Appendices

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
  • *.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

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.

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.

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 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.


If you have any questions, or see anywhere we can improve our documentation, please let us know!