HomeGuidesAPI Reference
Submit Documentation FeedbackJoin Developer CommunityLog In

Setup - Edge Subdomain

This is the documentation for Performance Edge. If you'd like access, please reach out to your Optimizely account manager.

There are several options for implementing Performance Edge, but we recommend using Edge Subdomain.

This method enables your site to directly and securely make requests to our Edge Decider making it the quickest and simplest way to get started with Performance Edge.

How Edge Subdomain Works

  1. A script on your site initiates a DNS lookup to your custom subdomain (e.g. optimizely.customer.com).

  2. Your DNS provider tells the visitor’s browser to send the request to cname.optimizely-edge.com because of a CNAME record that aliases your subdomain to cname.optimizely-edge.com.

  • You’ll need to add this CNAME record as part of the implementation.
  • If you define a CAA record on your domain, make sure it allows either DigiCert or Let's Encrypt as a CA. If your domain does not allow either CA, then you will need to use a CDN Proxy implemntation.
  1. Our Edge Decider processes requests sent to cname.optimizely-edge.com and returns a microsnippet that runs on your site to apply your experiments.
  • See our documentation on How it works for the full details of what the Edge Decider does and what it returns.

What about a direct request to cname.optimizely-edge.com?

The reason the script needs to make a request to your custom subdomain as opposed to cname.optimizely-edge.com directly is to allow Optimizely to access cookies on your site. The list of cookies that Optimizely reads can be found here.

If you target an audience based on cookie values, the Edge Decider needs access to those cookies as well.

📘

Privacy Note

On every request to a particular domain, browsers send all cookies that that domain has access to. What this means is that using your subdomain to make the request gives Optimizely’s Edge Decider access to all the cookies that your subdomain has access to.

Optimizely only reads from the cookies listed here and any cookies that you target an audience with.

Though (with the exception of the cookies listed here) Optimizely does not store or modify any cookies you send to the Edge Decider, we recommend limiting the cookies that your subdomain has access to as much as possible and ensure that no direct personal identifiers (e.g. name, email, address) are included in cookies sent to Optimizely.

  • You can prevent cookies from being sent by not scoping these cookies to your chosen subdomain (e.g. optimizely.customer.com) or parent domain (e.g. customer.com) of your site.

If you have concerns with granting Optimizely access to the abovementioned cookies, we would recommend implementing Edge using a CDN Proxy where you have the ability to control which cookies are included in or excluded from the Optimizely Edge Decider request.

Instructions for Implementing Edge Subdomain

  1. Add a CNAME record at your DNS provider to create an alias from your selected subdomain (e.g. optimizely.customer.com) to cname.optimizely-edge.com.

  2. Contact your account team and let them know you’re interested in implementing Performance Edge via Edge Subdomain.

  • Let them know which subdomain you would like to use to make requests from (e.g. optimizely.customer.com).
  • On our end, we’ll prepare our infrastructure to securely receive your requests from your subdomain.
  1. Your account team will let you know when we’re prepared to receive your requests. This can usually be done within 2 business days.

  2. Once you hear from your account team, you should implement the Edge script tag on your site. You can generate this script tag in your Project Settings:

The script tag should look similar to this:
<script src="https://optimizely.customer.com/edge-client/v1/1234567/6543210" referrerpolicy="no-referrer-when-downgrade"></script>

📘

Referrer Policy Attribute

The referrerpolicy attribute is required in your script tag to enable Optimizely to receive the referrer for page targeting purposes.

Starting in Chrome 85, Chrome will default to using the strict-origin-when-cross-origin referrer policy which would prevent Optimizely from getting the full URL of the page the visitor is viewing. Other browsers have indicated they plan to follow Chrome’s lead in this as well. Setting the referrer policy to the current default no-referrer-when-downgrade resolves this. Learn more about these referrer policies.

👍

How to Add the Script Tag

For best performance, we recommend adding the script tag at the top of the <head> tag of the HTML document of the page you want to run Performance Edge on.

Also, do not include the async attribute in your script tag or else your site will be prone to flashing when the microsnippet response from the Edge Decider executes on your site.

<html>
  <head>
    <script src="https://optimizely.customer.com/edge-client/v1/1234567/543210" 
            referrerpolicy="no-referrer-when-downgrade">
    </script>
    <!-- Other Scripts  -->
  </head>
  <body>
      <!-- Your Site Content -->
  </body>
</html>

Verify your Setup

To verify your setup and ensure that the correct data is received in the browser, start by checking that the Edge Decider returns a microsnippet to your browser.

  1. Load the webpage that has the <script> tag on it.
  2. In the JavaScript console, run optimizelyEdge.
  3. If optimizelyEdge returns defined, you've implemented Performance Edge successfully.

Congratulations! You're now ready to create an experiment!


Did this page help you?