> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duckie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chrome Extension

> Deploy the Duckie widget for support agents via a Chrome extension — no site embedding required

The Duckie Chrome extension lets support agents use the Duckie widget directly in their browser without requiring a script tag on any website. It automatically injects the widget on pages that match a condition you configure — for example, your Zendesk or Freshdesk agent workspace.

## How it works

The extension checks each page the agent visits against the deployment's configured condition (a localStorage key, cookie, URL parameter, or other browser signal). If the condition passes, it injects the widget automatically. The widget behaves identically to an embedded widget — it collects browser metadata, creates a session, and connects to your agent.

The widget key in the extension identifies your organization and deployment. No per-agent login is required.

## Download

Get the extension from the Duckie dashboard:

1. Go to **Connections → Widget**
2. Click **Get Embed Code**
3. Open the **Extension** tab
4. Click **Download Extension (.zip)**

## Installation

### Self-serve (individual agent)

1. Download and unzip the extension file
2. Open Chrome and go to `chrome://extensions`
3. Enable **Developer mode** (toggle in the top right)
4. Click **Load unpacked** and select the unzipped folder
5. Click the Duckie extension icon in the toolbar → **Options**
6. Enter your widget key (found in **Connections → Widget → Get Embed Code**) and save

The widget will appear on any page where the extension condition passes.

### Enterprise (Google Workspace)

IT admins can force-install the extension and push the widget key to all agents without any manual setup.

**Step 1 — Force install via Google Admin Console**

1. Go to **Devices → Chrome → Apps & Extensions**
2. Select the target organizational unit
3. Add the extension (by ID or upload the `.crx` file)
4. Set the install policy to **Force Install**

**Step 2 — Push the widget key via managed policy**

On the same extension entry, paste the following into the **Policy for extensions** field, replacing the values with your own:

```json theme={null}
{
  "widgetKey": {
    "Value": "wgt_your_widget_key"
  },
  "baseUrl": {
    "Value": "https://app.useduckie.ai"
  }
}
```

The `widgetKey` and `baseUrl` are shown pre-filled in the **Get Embed Code → Extension** tab for your widget.

Agents receive the configuration automatically on their next Chrome sync — no manual entry needed.

<Info>
  If a managed policy key is present, the extension options page is locked and agents cannot change the widget key.
</Info>

## Configure the injection condition

The extension only injects the widget when a condition you define passes on the current page. Without a condition configured, the widget will not appear.

Configure the condition per widget deployment:

1. Go to **Deploy → your widget deployment → Edit**
2. Scroll to **Chrome Extension Condition**
3. Toggle it on and configure:

| Field              | Description                                                                                                 |
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
| **Read from**      | Where to check: `localStorage`, `sessionStorage`, `Cookie`, `URL Parameter`, `JS Expression`, or `Meta tag` |
| **Key**            | The key or name to read (e.g. a localStorage key or cookie name)                                            |
| **Expected value** | Optional. If set, the value must match exactly. If blank, any truthy value passes.                          |

**Example conditions**

| Goal                                        | Source        | Key                                             |
| ------------------------------------------- | ------------- | ----------------------------------------------- |
| Inject on any authenticated Zendesk session | Cookie        | `_zendesk_session`                              |
| Inject only on the agent workspace          | JS Expression | `window.location.pathname.startsWith('/agent')` |
| Inject when a custom flag is set            | localStorage  | `duckie_enabled`                                |

The condition is re-evaluated on each page load. Changing the condition in the dashboard takes effect on the next page load — no extension update required.

## Passing browser metadata

Data you configure in the widget's **Metadata** tab is collected automatically by the extension and passed to the agent as **Widget App Data** — the same as a standard widget embed.

For example, if you configure a metadata field to read `ticketId` from `localStorage`, the agent receives it with every conversation started from that page.

See the [website widget](/integrations/messaging/widget) page for metadata field configuration.

## Troubleshooting

**Widget does not appear**

* Confirm the widget key is saved in the extension options page
* Check that the deployment has a Chrome Extension Condition configured and toggled on
* Verify the condition passes on the current page (e.g. run `localStorage.getItem('your_key')` in the browser console)
* Reload the page after saving a new condition

**Widget appears but sends no metadata**

* Ensure the metadata field's localStorage key (or other source) exists on the page before the widget loads
* Set the value before the page loads, not after — embed.js collects metadata on initialization

**Managed policy key not applying**

* Confirm the agent is signed into Chrome with their managed Google Workspace account
* Policy changes can take a few minutes to propagate; ask the agent to restart Chrome