# @birdie-so/snippet

Easily integrate the Birdie screen recording snippet into your application using modern frameworks like **React**, **Vue**, **Angular**, or plain **JavaScript** — with full control over initialization, metadata, and event hooks.

> ⚡ This package is a helper utility for integrating Birdie.  
> **You must have a Birdie account and a valid `clientId` to use this package.**  
> It does **not work on its own** — visit [https://app.birdie.so](https://app.birdie.so) to get started.

> ⚡ The core logic is still loaded from our CDN. This package is just a light wrapper for easier integration and customization.

![npm](https://img.shields.io/npm/v/@birdie-so/snippet?label=npm%20version)
![license](https://img.shields.io/npm/l/@birdie-so/snippet)

---

## 🚀 Installation

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

---

## ✨ Quick Start

### React / Vue / Angular / JS

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

initBirdie({
  clientId: "YOUR_CLIENT_ID", // required
  contact: {
    email: "alex@empire.com" // required to get logs capture
  }

  // Optional metadata available to recordings
  metadata: {
    user: {
      id: "123",
      email: "user@example.com",
    },
  },

  // Optional setting to remove response bodies when collecting logs
  settings: {
    privacy: {
      mask_response_body: true
    }
  },

  // Optional hook once Birdie is ready
  onReady(birdie) {
    // you can register for the following events
    birdie.on("recorderOpen", (data) => {
      console.log("Recorder tab is opened", data);
    });
    birdie.on("start", (data) => {
      console.log("Recording started", data);
      birdie.metadata = { dynamicKey: "value" };
    });
    birdie.on("pause", (data) => {
      console.log("Recording paused", data);
    });
    birdie.on("resume", (data) => {
      console.log("Recording resumed", data);
    });
    birdie.on("stop", (data) => {
      console.log("Recording stopped", data);
    });
    birdie.on("restart", (data) => {
      console.log("Recording restarted", data);
    });
    birdie.on("captureStarted", (data) => {
      console.log("Capturing logs started", data);
    });
    birdie.on("captureStopped", (data) => {
      console.log("Capturing logs stopped", data);
    });
    birdie.on("recordingSent", (data) => {
      // data.link contains the link to the video
      console.log("A new recording has been sent", data);
    });
    birdie.on("recorderClose", (data) => {
      console.log("Recorder tab was closed", data);
    });
    birdie.on("error", (error) => {
      console.log("Something went wrong", error);
    });

    // you can also update data after initialization
    birdie.update({
        contact: {
            email: "john@empire.com"
        },
        metadata: {
            parameter: "value"
        }
    });
  }

});
```

---

## 🧠 How It Works

This package:

- Injects the Birdie CDN snippet dynamically using your `clientId`.
- Sets global `window.birdieSettings` before loading.
- Registers event callbacks once the Birdie SDK is ready (`window.birdie` is available).

Your original snippet like this:

```html
<script>
  window.birdieSettings = {
    /* ... */
  };
</script>
<script src="https://cf.birdie.so/widget/embed/YOUR_CLIENT_ID"></script>
```

Is now handled via code with `initBirdie()`.

---

## 🧩 Advanced

### Get Birdie instance later

```js
import { getBirdieInstance } from "@birdie-so/snippet";

getBirdieInstance((birdie) => {
  birdie.on("start", () => {
    console.log("Recording started!");
  });
});
```

Or synchronously:

```js
const birdie = getBirdieInstance();
if (birdie) {
  birdie.metadata = { key: "value" };
}
```

---

## 📘 Docs

For full documentation and integration examples, visit [our docs page](https://docs.birdie.so/birdie-docs/request-screen-recordings/installation/snippet)

---

## 🛠 Support

Need help? Reach out to us at [support@birdie.so](mailto:support@birdie.so)

---

## 📄 License

MIT