👾Snippet

How to install the Birdie snippet

Birdie Snippet is required for capturing logs.

Birdie Snippet is required if you want to hide sensitive data.

Birdie automatically captures console logs when a user records an issue.

Setup overview

To capture console logs, you need to:

Install the Birdie snippet on your app
Whitelist Birdie in your Content Security Policies
Identify your users with an email
Configure a recording page

1. Install the Birdie snippet

You can choose between 2 options:

Option A: Frontend Integration using NPM

npm install @birdie-so/snippet
# or
yarn add @birdie-so/snippet

Use with React / Vue / Angular / JS

You must get your own clientId, get it from your Birdie Settings → Logs section.

import { initBirdie } from "@birdie-so/snippet";

initBirdie({
  clientId: "YOUR_CLIENT_ID", // required
  contact: {
    email: "[email protected]", // required to get logs
    name: "Alexander" // optional
    id: 65523 // optional
  },

  // Optional metadata available to recordings
  metadata: {
    any: {
      key: "123",
      product_id: "EBF-233",
    },
  },

  // Optional hook once Birdie is ready
  onReady(birdie) {
    birdie.on("start", (data) => {
      console.log("Recording started", data);
      birdie.metadata = { dynamicKey: "value" };
    });

    birdie.on("stop", (data) => {
      console.log("Recording stopped", data);
    });
    
    // if you need to update the contact email after initialization:
    birdie.update({ contact: { email: "[email protected]" } })

    // or update your metadata:
    birdie.update({ metadata: { status: { id: "123", label: "active", color: "#000000" } } })
    
  },
});

👉 You will find some more infos about implementation in this page.

Option B: Manual installation

We do not recommend installing Birdie through Google Tag Manager or Segment. The preferred method is to paste the code directly onto your web application, as this will result in faster load times.

Go to Settings → Logs
Click on Send to developer, or Copy the snippet code and paste it in the <head> section of your web app. Note that the snippet is unique to your organization.

How to add custom medatada

Optionally add your own metadata if you need to store additional data along the recordings like this:

// 1st method: add this before loading the snippet
window.birdieSettings = {
    contact_email: "[email protected]",
    metadata: {
        mykey: "value",
        otherkey: [
            { x: 12, y: 13 },
            { opacity: 35, width: 440 }
        ]
    }
}

// 2nd method, add metadata after loading the snippet: 
if (window.birdie) {
    window.birdie.metadata = {
        mykey: "value",
        otherkey: [
            { x: 12, y: 13 },
            { opacity: 35, width: 440 }
        ]
    }
}

💡 Note that if you have several tabs open with the snippet loaded, only the latest metadata that was set will be available along a recording.

How to hook into recorder events

Optionally you can register for events to know when a recording has started and stopped. First make sure window.birdie object is present by registering for onBirdieReady event before loading the snippet, then register for "start" and "stop" events like this:

window.birdieReadyCallback = function() {
  console.log("Birdie Ready, window.birdie object is now available")
  window.birdie.on('start', function(data) {
    console.log("A recording was started", data);
    // save custom data, or add metadata
    window.birdie.metadata = { key: "value" }
  });
  window.birdie.on('stop', function(data) {
    console.log("A recording was stopped", data);
  });
}
  
window.birdieSettings={
  onBirdieReady: birdieReadyCallback
}

// then add the snippet…

2. Whitelist Birdie in your Content Security Policy

To ensure proper functionality, whitelist the following:

HTTPS: https://*.birdie.so
Secure WebSocket protocol: wss://*.birdie.so
Port: 443, 3478 (TCP and UDP)
IP Address: 18.189.92.9 and 3.20.198.186

3. Identify your customer with an email

This step is optional if your app uses one domain, or multiple subdomains of the same domain

Examples: - app.acme.com - dashboard.acme.com - customerX.acme.com - customerY.acme.com

All of these belong to the same domain: acme.com

👉 Using multiple domains? If your app spans multiple domains, this step is required. Reach out to our team so we can enable the multi domain solution for your workspace.

Capturing logs with the Birdie Screen Recorder for a given user requires that the same user email be used both in the recorder and in your snippet. The setup depends on how you installed the snippet:

If you installed with NPM

Set the contact: { email: ""} value, or update it as soon as you have it. See full example above:

onReady(birdie) {
    birdie.update({ contact: { email: "[email protected]" } })
    ...

If you installed manually

Add contact_email info in your window.birdieSettings . See example above:

window.birdieSettings = {
    contact_email: "[email protected]",
    ...

4. Configure and verify your recording page

This step is required if your app uses one domain, or multiple subdomains of the same domain

Examples: - app.acme.com - dashboard.acme.com - customerX.acme.com - customerY.acme.com

All of these belong to the same domain: acme.com

👉 Using multiple domains? If your app spans multiple domains, this step does not apply. Instead, reach out to our team so we can enable the multi domain solution for your workspace.

When a customer opens a Birdie recording link, Birdie needs a page on your site to display the recording interface.

This page is called your recording page.

You choose which page Birdie should use, then add that URL in your Birdie logs settings.

This lets Birdie launch the recorder directly from your site.

Think of it as a simple entry point on your site where Birdie launch the recorder.

This allows customers to record their screen directly from your site.

Step 1: Create your recording page

The best practice here is to create a dedicated recording page on your app.

Example:

https://app.acme.com/recorder

This page should:

include the Birdie snippet
be on the same domain as your app
be a blank page
be accessible without authentication (like your login page)
not redirect anywhere

👉 This ensures your recorder works reliably in all situations.

Important: redirects can break the recorder

If your recording page redirects users, for example to a login page, Birdie parameters may be lost.

Example:

https://app.acme.com/recorder?birdie-recording=...

If these parameters are removed:

the recording interface will not appear
logs will not be captured.

Requirement: preserve query parameters

If your app performs redirects, your developers must ensure that:

the full query string is preserved, or
parameters are forwarded to the destination page

What happens when a recording starts

When a customer opens a recording link:

Birdie opens your recording page
The Birdie snippet loads
The recording interface appears
Logs are captured during the session across your app

What logs Birdie collects

Birdie collects logs from pages that:

run the Birdie snippet
are on the same domain as the recording

That means:

a recorder started on acme.com can collect logs from sub.acme.com
a recorder started on sub.acme.com can collect logs from ace.com

👉 This is why the page must be on your domain and include the Birdie snippet.

Step 2: Add your recording page in Birdie

Go to your Birdie logs settings:

Enter your recording page URL
Click Verify

Birdie will check that your setup is correct before enabling log collection:

Quick test before verifying

Before clicking Verify :

Open your recording page in an incognito window
Add a test parameter, for example:
```
https://app.acme.com/recorder?test=1
```
Check that:
- the page does not redirect, or
- the parameter is still present after redirect

If the parameter disappears, your setup needs adjustment.

What if verification fails or the recorder does not appear?

Common causes:

The page redirects and removes query parameters
The Birdie snippet is not installed on the page
The page is on a different domain

👉 These issues prevent the recorder from starting correctly.

Can I set it up in a testing (staging) environment?

If you want to test your setup before using it in production, you can also configure a testing environment.

This works the same way as your main setup, but is intended for internal testing only.

When configured, you will see a separate “Testing environment” section in your Birdie logs settings.

Important differences

The testing environment behaves slightly differently from your production setup:

it is designed for internal testing only
it does not use your helpdesk integration
recordings must be triggered manually

How to test your staging setup

To test your staging environment:

Go to your Birdie logs settings
Find the Testing environment section
Click Request a recording

👉 This will generate a recording link that you can use to validate your setup.

Important

The testing environment will not work through your helpdesk integration.

You must use the “Request a recording” link to test it:

Subdomains and Safari limitation

IIn Safari, logs are only captured when the snippet is running on the exact same subdomain.

Tip: when a snippet is loaded into your app, a cookie named __birdie_snippet_status is maintained as long as the snippet is loaded, and expires 60s after the snippet is unloaded. If you need to detect the presence of the snippet in one of your pages you can test the presence of this cookie.

If you need help or have a question, contact us at [email protected]

PreviousCustom Domain Setup NextBrowser compatibility

Last updated 40 minutes ago

hashtagSetup overview

hashtag1. Install the Birdie snippet

hashtagOption A: Frontend Integration using NPM

hashtagOption B: Manual installation

hashtag2. Whitelist Birdie in your Content Security Policy

hashtag3. Identify your customer with an email

hashtag4. Configure and verify your recording page

hashtagStep 1: Create your recording page

hashtagImportant: redirects can break the recorder

hashtagRequirement: preserve query parameters

hashtagWhat happens when a recording starts

hashtagStep 2: Add your recording page in Birdie

hashtagQuick test before verifying

hashtagImportant differences

hashtagHow to test your staging setup

hashtagImportant

Setup overview

1. Install the Birdie snippet

Option A: Frontend Integration using NPM

Option B: Manual installation

2. Whitelist Birdie in your Content Security Policy

3. Identify your customer with an email

4. Configure and verify your recording page

Step 1: Create your recording page

Important: redirects can break the recorder

Requirement: preserve query parameters

What happens when a recording starts

Step 2: Add your recording page in Birdie

Quick test before verifying

Important differences

How to test your staging setup

Important