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

# Introduction

> Prepare your extension and install the web extension SDK into your browser extension.

You can integrate Sleek into your browser extension as a JavaScript or
TypeScript package. You will find a quick guide to setup Sleek in your browser
extension below.

## Setup

<Note>
  Before you start, ensure that you have your Sleek credentials on hand.
  [Contact support](mailto:support@onsleek.com) if you need help with your
  credentials.
</Note>

### Extension Permissions

The correct extension permissions must be requested for Sleek to function. Sleek
requires the following permissions be requested by your browser extension:

* `storage`
* `tabs`
* `webRequest`
* `scripting`

Add the permissions to your manifest file like the below snippet:

<CodeGroup>
  ```json Manifest v2 theme={null}
  "permissions": [
    ... your other permissions,
    "storage",
    "tabs",
    "webRequest",
    "scripting",
    "<all_urls>" // In manifest v2, you must add host permissions in the `permissions` array.
  ]
  ```

  ```json Manifest v3 theme={null}
  "permissions": [
    ... your other permissions,
    "storage",
    "tabs",
    "webRequest",
    "scripting"
  ]
  ```
</CodeGroup>

More information on browser extension permissions can be found
[here](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions)
or on your respective browser extension's developer portal.

### Host permissions (manifest v3 only)

In addition to permissions for extensions using manifest v3, Sleek requires your
extension to operate on the correct URLs in the browser. In manifest v2, you specify host permissions along with other API permissions in the `permissions` array. Sleek runs CAA on every e-commerce page that the user interacts with. To do
so, Sleek requires the following host permissions:

```json theme={null}
"host_permissions": [
  ... other hosts your extension operates on,
  "<all_urls>"
]
```

## Installation

Sleek's Web Extension SDK is bundled and served in a private package repo. To
integrate the package into your dependencies, you will need to tell your package
manager to get the `@sleek/web-ext-sdk` package from Sleek's private repo.

### Recommended private package setup

We recommend taking a dependency on Sleek's private package repo for the
`@sleek/web-ext-sdk` package. In addition, we recommend a setup where the
package repo URL is maintained by a `.npmrc` file in the root of your project's
directory.

<Info>
  You can consume the private `@sleek/web-ext-sdk` in whatever fashion
  best fits your needs. Use the private repo URL listed below and follow steps
  for your package manager.
</Info>

**npm and pnpm**

Add the following line to your `.npmrc` file in the root of your directory:

```text theme={null}
@sleek:registry=https://npm.cloudsmith.io/sleek/sleek/
//npm.cloudsmith.io/sleek/sleek/:_authToken={YOUR_TOKEN_HERE}
```

The above file will ensure that packages in the `@sleek` scope (like our
`@sleek/web-ext-sdk`) will be fetched from our private repo, when
installed and updated.

You should commit the resulting `.npmrc` file, if you aren't already, so that
your collaborators can use Sleek's web extension SDK as well.

<Warning>
  **Sleek web extension SDK access tokens are private**

  Ensure that your token in the `_authToken` field above is secured like any other
  secret key in your organization.
</Warning>

### Add the SDK to your dependencies

Install Sleek's Web Extension SDK using the below command and your package
manager will resolve and download the package from the private repository.

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm add @sleek/web-ext-sdk
  ```

  ```bash npm theme={null}
  npm install @sleek/web-ext-sdk
  ```
</CodeGroup>

### Add static SDK files

Sleek requires the following scripts, included with the SDK, to be available in
the extension package: `mf.js` and `f.js`.

The static scripts can be found in the downloaded web-ext-sdk package:
`node_modules/@sleek/web-ext-sdk/dist/*`.

Copy the scripts into the root of your outputted and packaged web extension. We
recommend adding this step to your build pipeline. i.e. `mf.js` and `f.js` should be in the
root of your extension, at the same level as your `manifest.json`.

## Usage

Register Sleek in the background context of your extension in the construction
lifecycle. Pass, at minimum, your client-side public Sleek API key to the setup.

<Warning>
  If you plan to call `getWebExtSdk()` immediately after initialization, you must `await`
  the `initializeWebExtSdk()` promise first. The SDK is not available until initialization completes.
</Warning>

```javascript theme={null}
import { initializeWebExtSdk } from "@sleek/web-ext-sdk";

// In your background script constructor or setup.
await initializeWebExtSdk(process.env.YOUR_SLEEK_CLIENT_API_KEY_HERE, {
  // Your options here.
});

// Now it's safe to use the SDK
getWebExtSdk().registerEventListener((event, tabDetails) => {
  // React to event here.
});
```

In the second parameter of the initialize call, you can provide Sleek with a
variety of options to customize your integration. The web extension SDK is typed
with bundled TypeScript types, so if you're interested in any other capabilities
or options in the initialization, check out the types or the [reference
here](/web-ext-sdk-reference/type-doc).

## Excluding sites from content script injection

The Sleek SDK comes with a built-in filter list of popular non-ecommerce sites
(e.g. Facebook, Gmail, YouTube, banks, etc.) where Sleek’s content scripts will never run.

If you want to extend this list, you can provide your own denylistMatches array in the SDK
initialization options. Your patterns will be merged with and deduplicated against Sleek’s built-in filter.

```javascript theme={null}
import { initializeWebExtSdk } from "@sleek/web-ext-sdk";

// In your background script constructor or setup.
await initializeWebExtSdk(process.env.YOUR_SLEEK_CLIENT_API_KEY_HERE, {
  denylistMatches: [
    "*://*.example.com/*",
    "*://*.internal.org/*"
  ],
});
```

This option ensures you stay in full control: Sleek will skip all domains in its default denylist, plus any
additional domains you provide.

### Event handling

Sleek can notify your extension when actions occur. For example, your extension
might want to listen to when an affiliate activation is detected. To register an
event listener for any of the supported events, use the SDK instance method
`registerEventListener`:

```javascript theme={null}
import { getWebExtSdk } from "@sleek/web-ext-sdk";

// In the background context.
getWebExtSdk().registerEventListener((event, tabDetails) => {
  // React to event here.
});
```

`registerEventListener` is [typed](/web-ext-sdk-reference/type-doc), so if you are
calling with TypeScript, the event types are present in the package's types and
the callback method will have data correctly typed as well. You can check
`event` (seen above) against [`WebExtensionSdkEventType & SdkEventType`](/web-ext-sdk-reference/type-doc) to see what
event was emitted.

**What's next:**

Now that the Sleek web extension SDK is embedded into your browser extension, Sleek is
automatically turned on and ready for you to extend into user experiences in
your extension. Check out the below documentation for more information on how to
use specific feature sets in the web extension SDK.

<CardGroup col={2}>
  <Card title="Enable coupon auto-apply" icon="robot" href="/web-ext-sdk-reference/coupon-auto-apply">
    Learn how to enable coupon auto-apply in your extension.
  </Card>

  <Card title="Enable page classification" icon="shapes" href="/web-ext-sdk-reference/page-classification">
    Learn how to enable page classification in your extension.
  </Card>

  <Card title="Enable product extraction" icon="pickaxe" href="/web-ext-sdk-reference/product-extraction">
    Learn how to enable product extraction in your extension.
  </Card>

  <Card title="Enable order extraction" icon="cart-shopping" href="/web-ext-sdk-reference/order-extraction">
    Learn how to enable order extraction in your extension.
  </Card>

  <Card title="Affiliate activation detection" icon="radar" href="/web-ext-sdk-reference/affiliate-activation-detection">
    Learn how the SDK detects affiliate activations.
  </Card>

  <Card title="Get installed extensions" icon="cubes" href="/web-ext-sdk-reference/installed-extensions">
    Learn how to get other installed extensions on user's browser.
  </Card>

  <Card title="View TypeDoc" icon="terminal" href="/web-ext-sdk-reference/type-doc">
    Browse the reference TypeDoc for the web extension SDK.
  </Card>
</CardGroup>

***

Need help? [Contact our support team](mailto:support@onsleek.com).