How to configure a Snippet v3 Domain

Overview

If you're using Ambassador widgets, the JS API, or the Ads Pixel for Programmatic Ads on your website, you'll install a snippet code that's custom to your account. Before you install it, create a Snippet v3 domain on the same website domain where the snippet will live.

The subdomain lets the snippet run as first-party code on your site. That keeps ad blockers and browser privacy protections from interfering, so your widgets load, the JS API tracks referral attribution, and programmatic ad attribution works the way it should. 🎯

Example snippet domain: snippet.companydomain.com

What is the Ambassador Snippet?

The Universal Snippet is a small piece of code you embed on your website. It powers:

• Ambassador widgets for referral, rewards, loyalty, marketing, surveys, and more
• The JS API, which tracks referrals, shares, and clicks
• The Ads Pixel, which tracks programmatic ad attribution

You can add it directly to your site or load it through a tag manager like Google Tag Manager or Adobe.

Step 1: Create your domain

1. In Ambassador, go to Admin & Configuration > Domains, select the Custom Domains tab, then select Add Domain.
2. Enter your subdomain. If your website is companydomain.com, something like snippet.companydomain.com works well.
3. Under Domain Usage, select Snippet V3 Domain.
4. Under Certificate Type, select Automatic.
5. Select Create Domain.

Step 2: Validate your hostname

Next, you'll prove you own the domain so Ambassador can serve the snippet through it. These steps happen in your DNS provider, not in Ambassador.

The exact screens vary by provider. We're using Cloudflare DNS in this example, but the same steps work anywhere.

1. Check the box next to the domain you just created and select View Domain. A Domain Details dialog opens with the values you'll need.
2. Create a CNAME record for your chosen subdomain, using the target shown in Domain Details. [CONFIRM: the original draft was missing the CNAME target value. What should customers point the record to?]
3. Create a TXT record named _cf-custom-hostname. The content is the Hostname verification value from Domain Details.
4. Wait for the status to update. This usually takes 5 minutes to 12 hours.

When the status changes to Pending certificate validation, you're ready for the last step.

Step 3: Validate your certificate

Finally, our custom domain provider issues a TLS certificate for your hostname. This is what tells browsers your snippet is being served securely.

1. Find the Certificate verification name and Certificate verification value in the Domain Details dialog.
2. Create another TXT record in your DNS. The name is the verification name, and the content is the verification value.
3. Once the certificate is requested, the status changes to Certificate requested.
4. Once it's issued, the status changes to Completed. You're done. ✅

Step 4: Install or update your snippet

What you do here depends on where you're starting from.

• Installing the snippet for the first time
  Go to Admin & Configuration > Integrations > Ambassador JS API. You'll find your code under Install the JS API Snippet, with your snippet domain already included. It's the same snippet for all three use cases: widgets, JS API, and Ads Pixel.
  
  
• You already have the snippet installed, but without a snippet domain
  Grab the new snippet code from the same place, then replace every instance of the old snippet on your website.
  
  
• You already have the snippet installed with a snippet domain from before October 1, 2026
  You'll also need to retrieve the updated snippet code and replace every instance of the old one. [CONFIRM: is this date correct, and is there a customer-facing reason worth naming here? Right now it reads as an arbitrary cutoff.]

Step 5: Test

Create a custom domain for every top-level domain you use. Then walk through your web pages and test your Ambassador features to confirm everything is loading through the new snippet domain.

Questions? Email support@getambassador.com