# Embed the snippet

URL: https://docs.ablyft.com/developers/installation/snippet/

> Add the ABlyft snippet to your website, directly or through Google Tag Manager.



To run experiments, you add one JavaScript snippet to your website. It contains the unique ID of your project.
You only install it once: when you change experiments, audiences or settings and publish them, the new data is
delivered under the same URL, so the snippet on your site never has to be edited.

```html
<script src="https://cdn.ablyft.com/s/12345678.js"></script>
```

In this example, `12345678` is the project ID. Replace it with your own.

## Get your snippet

1. Open your project in ABlyft.
2. Go to **Settings → Snippet**.
3. In the section **Snippet Implementation**, copy the code from **Implementation (base snippet)**.

The same section shows the state of your snippet, see
[Publishing](https://docs.ablyft.com/developers/installation/publishing/#check-the-state-of-your-snippet).

## Where to place it

Place the snippet in the `<head>` of every page you want to test, as early as possible and before your other scripts.
A good spot is right after the `<title>` or the meta tags and stylesheets.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <!-- more meta tags -->
    <!-- stylesheets -->
    <script src="https://cdn.ablyft.com/s/12345678.js"></script>
    <!-- more scripts -->
  </head>
  <body>
    ...
  </body>
</html>
```

## Synchronous or asynchronous

|           | Synchronous (default)                                                                 | Asynchronous                                                 |
| --------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| Code      | `<script src="…">`                                                                    | `<script async src="…">`                                     |
| Behavior  | The browser waits for the snippet before it renders the page                          | The snippet loads in parallel and does not block rendering   |
| Advantage | Prevents flicker: visitors do not see the original page before a variation is applied | Better loading performance, for example for PageSpeed scores |

Both variants are supported. Because the snippet loads very quickly, the difference is small. Use the synchronous version
if flicker is a concern.

```html
<script async src="https://cdn.ablyft.com/s/12345678.js"></script>
```

> With `async`, the page may be displayed briefly in its original state before a variation is applied.

## Google Tag Manager

You can also load the snippet through Google Tag Manager, without changing your site's code.

1. Copy your snippet as described [above](#get-your-snippet).
2. In Google Tag Manager, create a new tag of the type *Custom HTML*.
3. Paste the snippet into the tag.
4. Set the trigger so that the tag fires on the pages you want to test, then publish your container.

> **Flicker:** Loading the snippet through a tag manager can cause flicker: visitors may briefly see the original content before a
> variation appears. For the best result, place the snippet directly in the `<head>`.

## Self-hosting the snippet

Instead of the CDN version, you can serve the snippet from your own server. You then save every new version as a file
on your side and include that file in your pages. There are two ways to get the current version.

### A) Publication webhook (recommended)

ABlyft calls a URL of yours after every publication and sends the snippet in the request. Your script saves it as a
local file.

1. In the project, open **Settings → Snippet** and add the URL of your script under [publication webhooks](https://docs.ablyft.com/developers/installation/snippet-settings/#publication-webhooks).
2. Add a secret token of your choice as a GET parameter to that URL, for example `https://www.example.com/ablyft-webhook.php?token=…`,
   and check it in your script. This prevents others from writing a file with their own content.
3. Include the local file instead of the CDN URL, for example `<script src="/snippets/12345678.js"></script>`.

```php
<?php
// Example receiver: saves the published snippet as snippets/<project_id>.js
if (($_GET['token'] ?? '') !== 'YOUR_SECRET_TOKEN') {
    http_response_code(403);
    exit;
}

if ($_SERVER['HTTP_USER_AGENT'] !== 'ABlyft Publication Webhook') {
    http_response_code(403);
    exit;
}

$projectId = (int) ($_POST['project_id'] ?? 0);
$script = $_POST['snippet_script'] ?? null;

if ($projectId === 0 || $script === null) {
    http_response_code(400);
    exit;
}

file_put_contents(__DIR__ . "/snippets/{$projectId}.js", $script);
http_response_code(204);
```

Enable **Include JS** for the webhook, otherwise the request does not contain `snippet_script`. The user agent alone is
no protection, because anyone can send it; the token is what secures the endpoint.

### B) Pull the file from the CDN

Your server can also download the snippet from its CDN address on a schedule or on demand. In this case the cache
expiration (**ttl**) must be set to **Disable Caching**, so that you always receive the latest version. This setting is
read-only in the app, so ask ABlyft support to change it. See [Cache expiration](https://docs.ablyft.com/developers/installation/snippet-settings/#cache-expiration-ttl).

> A self-hosted file is only as current as your last update. If the webhook fails or your pull job stops, visitors keep
> receiving the old snippet. Monitor the webhook, and compare the revision number
> shown in **Settings → Snippet** with the one in your file after a publication.

## Good to know

* **Include it once per page.** If a second ABlyft snippet is found, it logs a warning and does not start.
* **iFrames:** The snippet does not run inside iFrames by default, see [Requirements](https://docs.ablyft.com/developers/installation/requirements/#iframes).
* **Environments:** to load less data on a specific site, use a [sub-snippet](https://docs.ablyft.com/developers/installation/environments/#sub-snippets) instead of the main snippet.
* **Bots** are excluded, see [Requirements](https://docs.ablyft.com/developers/installation/requirements/#bots).
* **Consent:** If you need visitor consent before tracking, see [Consent manager](https://docs.ablyft.com/developers/consent-and-security/consent-manager/).
* **Updates:** After publishing in ABlyft, it can take a short time until the new version is delivered, see
  [Cache expiration](https://docs.ablyft.com/developers/installation/snippet-settings/#cache-expiration-ttl).

## Check the installation

Verify that the snippet is requested and running with the checks in [Verify the integration](https://docs.ablyft.com/developers/debugging/verify-integration/),
or follow the [Quickstart](https://docs.ablyft.com/developers/quickstart/).