# Install Screeb with an AI coding agent

Instructions for AI coding agents asked to install Screeb in a project, with the install code of every SDK.

This guide is written for AI coding agents (Cursor, Claude Code, GitHub Copilot and others) asked to install Screeb in a project. Humans can follow it too. Its Markdown version is at [/install-with-ai.md](https://developers.screeb.app/install-with-ai.md).

Screeb shows in-app surveys and messages, and collects product feedback and session replays. Installing it means adding one SDK, initializing it with the workspace **channel id**, then telling Screeb who the user is and what they do.

## Ground rules

- **Channel id:** a public UUID identifying the Screeb workspace, safe to commit. The SDKs also call it `websiteId`: it is the same value. Replace `<YOUR-CHANNEL-ID>` with it. If the project keeps public client keys in config or environment variables, follow that convention; otherwise inline it.
- **Tag endpoint:** replace `<TAG-ENDPOINT>` with `https://t.screeb.app`, unless you were given another one.
- **One integration only:** pick one row in [Choose the integration](#choose-the-integration). Never install both the HTML snippet and an npm package.
- **Do not touch unrelated code:** no refactors, no formatting changes, no dependency upgrades beyond adding the Screeb package.
- **Use the project's package manager** (npm, yarn, pnpm, bun, CocoaPods, SPM, Gradle, pub, NuGet) and its lockfile. Always add the latest published version.
- **No secrets in Screeb properties:** never send passwords, tokens, API keys or payment data as user or event properties.
- **CI and tests:** do not load Screeb in automated test runs, which would create anonymous users. Guard the init with the project's existing environment flag if it has one.
- **Finish with a summary:** list the files you changed and tell the developer to open the app, then click **Verify installation** in Screeb (`https://admin.screeb.app/org/last/settings/install`).

## Choose the integration

Detect the stack from the project files (`package.json`, `angular.json`, `pubspec.yaml`, `Podfile`, `Package.swift`, `build.gradle(.kts)`, `*.csproj`), then pick the first matching row.

| Stack                                    | Integration                             | Full guide                                                             |
| ---------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------- |
| React Native                             | `@screeb/react-native`                  | [React Native](https://developers.screeb.app/sdk-react-native/install) |
| Flutter                                  | `plugin_screeb` (pub)                   | [Flutter](https://developers.screeb.app/sdk-flutter/install)           |
| Ionic / Capacitor                        | `@screeb/sdk-angular`                   | [Ionic](https://developers.screeb.app/sdk-ionic/install)               |
| Kotlin Multiplatform                     | `app.screeb.sdk.kmp:screeb-kmp`         | [Kotlin Multiplatform](https://developers.screeb.app/sdk-kmp/install)  |
| .NET MAUI                                | `Screeb.Maui` (NuGet)                   | [.NET MAUI](https://developers.screeb.app/sdk-maui/install)            |
| Native iOS (Swift)                       | `Screeb` (SPM or CocoaPods)             | [iOS](https://developers.screeb.app/sdk-ios/install)                   |
| Native Android (Kotlin or Java)          | `app.screeb.sdk:survey` (Maven Central) | [Android](https://developers.screeb.app/sdk-android/install)           |
| React (Vite, Next.js, Remix)             | `@screeb/sdk-react`                     | [React](https://developers.screeb.app/sdk-react/install)               |
| Angular                                  | `@screeb/sdk-angular`                   | [Angular](https://developers.screeb.app/sdk-angular/install)           |
| Vue (Vite, Nuxt)                         | `@screeb/sdk-vue`                       | [Vue](https://developers.screeb.app/sdk-vue/install)                   |
| Svelte / SvelteKit                       | `@screeb/sdk-svelte`                    | [Svelte](https://developers.screeb.app/sdk-svelte/install)             |
| Any other bundled JavaScript app         | `@screeb/sdk-browser`                   | [Browser](https://developers.screeb.app/sdk-browser/install)           |
| Plain HTML, server templates, no bundler | HTML snippet                            | [JavaScript tag](https://developers.screeb.app/sdk-js/install)         |

Screeb only runs in the browser. In Next.js, Nuxt, SvelteKit, Remix, Angular Universal or any server-side rendering setup, load and initialize it on the client only: a client component (`"use client"`), `onMounted`, `onMount`, `useEffect`, `afterNextRender`, or a `typeof window !== "undefined"` guard.

## JavaScript tag

Paste the snippet before `</body>` on every page, or in the shared layout.

```html
<!-- Screeb tag -->
<script>
  (function(s,c,r,ee,b){
    s.ScreebObject=r;
    if(typeof s[r]!="function")s[r]=function(){var d=arguments;return new Promise(function(o,k){(s[r].q=s[r].q||[]).push({v:1,args:d,ok:o,ko:k})})};
    b=c.createElement("script");b.id=r;b.src=ee;c.head.appendChild(b);
  })(window,document,"$screeb","<TAG-ENDPOINT>/tag.js");
  $screeb("init", "<YOUR-CHANNEL-ID>");
</script>
<!-- End of Screeb tag -->
```

## Browser

Add `@screeb/sdk-browser`, then load and initialize it once at app start.

```ts
import * as Screeb from "@screeb/sdk-browser";

Screeb.load();
Screeb.init("<YOUR-CHANNEL-ID>");
```

## React

Add `@screeb/sdk-react` and wrap the app root once. Call methods anywhere inside it with the `useScreeb()` hook.

```tsx
import { ScreebProvider } from "@screeb/sdk-react";

export const App = () => (
  <ScreebProvider autoInit websiteId="<YOUR-CHANNEL-ID>">
    <HomePage />
  </ScreebProvider>
);
```

## Vue

Add `@screeb/sdk-vue` and install the plugin on the app. Call methods with `useScreeb()`.

```ts
import { createApp } from "vue";
import { ScreebPlugin } from "@screeb/sdk-vue";
import App from "./App.vue";

createApp(App)
  .use(ScreebPlugin, {
    websiteId: "<YOUR-CHANNEL-ID>",
    autoInit: true,
  })
  .mount("#app");
```

## Angular

Add `@screeb/sdk-angular` and import the module at bootstrap. Inject the `Screeb` service to call methods.

```ts
import { importProvidersFrom } from "@angular/core";
import { bootstrapApplication } from "@angular/platform-browser";
import { ScreebModule } from "@screeb/sdk-angular";
import { AppComponent } from "./app/app.component";

bootstrapApplication(AppComponent, {
  providers: [
    importProvidersFrom(
      ScreebModule.forRoot({
        autoInit: true,
        websiteId: "<YOUR-CHANNEL-ID>",
      }),
    ),
  ],
});
```

## Svelte

Add `@screeb/sdk-svelte` and set the context in the root component. Call methods with `useScreeb()`.

```ts
// In the <script lang="ts"> block of your root component (App.svelte)
import { setScreebContext } from "@screeb/sdk-svelte";

setScreebContext({
  websiteId: "<YOUR-CHANNEL-ID>",
  autoInit: true,
});
```

## iOS

Add the package (SPM: `https://github.com/ScreebApp/sdk-ios-public`, or CocoaPods: `pod "Screeb"`), then initialize it at launch.

```swift
import Screeb
import UIKit

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Screeb.initSdk(
            context: nil,
            channelId: "<YOUR-CHANNEL-ID>"
        )
        return true
    }
}
```

## Android

Add `implementation("app.screeb.sdk:survey:<latest>")` from Maven Central, then initialize it in `Application.onCreate`.

```kt
import android.app.Application
import app.screeb.sdk.Screeb

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Screeb.initSdk(this, "<YOUR-CHANNEL-ID>")
    }
}
```

## React Native

Add `@screeb/react-native`, run `pod install` in `ios/`, then initialize it once at app start.

```tsx
import * as React from "react";
import { initSdk } from "@screeb/react-native";

export default function App() {
  React.useEffect(() => {
    initSdk("<YOUR-CHANNEL-ID>");
  }, []);

  return <HomeScreen />;
}
```

## Flutter

Add the plugin with `flutter pub add plugin_screeb`, then initialize it at app start.

```dart
import 'package:flutter/material.dart';
import 'package:plugin_screeb/plugin_screeb.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  PluginScreeb.initSdk("<YOUR-CHANNEL-ID>");
  runApp(const MyApp());
}
```

## Ionic

Ionic apps use the Angular package: add `@screeb/sdk-angular` and import the module at bootstrap.

```ts
import { importProvidersFrom } from "@angular/core";
import { bootstrapApplication } from "@angular/platform-browser";
import { provideIonicAngular } from "@ionic/angular/standalone";
import { ScreebModule } from "@screeb/sdk-angular";
import { AppComponent } from "./app/app.component";

bootstrapApplication(AppComponent, {
  providers: [
    provideIonicAngular(),
    importProvidersFrom(
      ScreebModule.forRoot({
        autoInit: true,
        websiteId: "<YOUR-CHANNEL-ID>",
      }),
    ),
  ],
});
```

## Kotlin Multiplatform

Add `app.screeb.sdk.kmp:screeb-kmp` to the shared module, then initialize it from each platform.

```kt
import app.screeb.sdk.kmp.Screeb

// From a coroutine started at app launch
Screeb.initSdk(
    channelId = "<YOUR-CHANNEL-ID>",
)
```

## .NET MAUI

Add the `Screeb.Maui` NuGet package, then initialize it at app start.

```cs
using static Screeb.Maui.Screeb;

// At app start, for example in App.OnStart
await InitSdk(channelId: "<YOUR-CHANNEL-ID>");
```

## Mobile apps: deep links and media

- **Deep links:** the Screeb in-app message editor opens the app through the URL scheme `screeb-<YOUR-CHANNEL-ID>`. Register it (`CFBundleURLSchemes` in `Info.plist` on iOS, an intent filter on the main activity on Android) and forward opened URLs to the SDK's `handleDeepLink`. The install guide of each mobile SDK has the exact code.
- **Audio and video answers:** if the app has an `Info.plist`, add `NSCameraUsageDescription` and `NSMicrophoneUsageDescription` when they are missing. Without them, iOS hides audio and video answers.

## Strict Content Security Policy and dedicated platforms

Apply these only when they concern the project:

- **Content Security Policy:** when the project sets a `Content-Security-Policy`, merge the Screeb sources into it rather than replacing it, as listed in [Security requirements](https://developers.screeb.app/sdk-js/security-requirements). Screeb never needs `'unsafe-eval'` or `'unsafe-inline'`.
- **Dedicated platform:** when you were given a platform name, add `s["ScreebConfig"] = { platform: "<PLATFORM>" };` as the first line inside the HTML snippet function, or pass `{ platform: "<PLATFORM>" }` as the load options of the npm SDKs. On iOS, add `<key>ScreebPlatform</key><string><PLATFORM></string>` to `Info.plist`; on Android, add `<meta-data android:name="app.screeb.sdk.PLATFORM" android:value="<PLATFORM>" />` inside `<application>`.

## Identify users and track a first event

Find where the app learns who the signed-in user is: the auth provider callback, the session or user store, a `/me` request. On login, and on app start when a session already exists, call the identity method of the SDK with a **stable internal user id** (not a display name) and a few useful properties (`email`, `plan`, `role`). On logout, call its reset method. See the identity guide of the chosen SDK, for example [React](https://developers.screeb.app/sdk-react/identity).

Then pick the product's primary call to action (sign-up, create, checkout, invite) and track it where the action succeeds, not on every render, with a short `snake_case` name such as `project_created`. See the event tracking guide of the chosen SDK, for example [React](https://developers.screeb.app/sdk-react/event-tracking).

## Check your work

- The app builds and starts. Screeb loads on the client only.
- Exactly one Screeb integration is installed.
- The channel id is the one you were given.
- Tell the developer: "Open the app once, then click **Verify installation** in Screeb."
