Pre-requisites: You need to set up your Kobble account.

Suggested boilerplate

Although there are many Chrome Extension boilerplate available on GitHub, we figured many of them just don’t work.

So we suggest you use Jonghakseo/chrome-extension-boilerplate-react-vite

Install the SDK

1

Install @kobbleio/react-web-extension

Install the @kobbleio/react-web-extension sdk with the provider of your choice.

npm install @kobbleio/react-web-extension
2

Use the KobbleProvider

To use the SDK, you must wrap your Popover or Tab component with the KobbleProvider component.

Here’s an example taken from our Chrome Extension boilerplate.

import { createRoot } from 'react-dom/client';
import '@src/index.css';
import Newtab from '@src/Newtab';
import { KobbleProvider } from "@kobbleio/react-web-extension";

function init() {
    const appContainer = document.querySelector('#app-container');
    if (!appContainer) {
        throw new Error('Can not find #app-container');
    }
    const root = createRoot(appContainer);

    root.render(
        <KobbleProvider domain={'YOUR_KOBBLE_DOMAIN'} clientId={'YOUR_CLIENT_ID'}>
            <Newtab />
        </KobbleProvider>
    );
}

init();
3

Replace the KOBBLE DOMAIN and CLIENT ID

In the above snippet, don’t forget to replace YOUR_KOBBLE_DOMAIN and YOUR_CLIENT_ID with your actual Kobble domain and client ID.

KOBBLE_DOMAIN and KOBBLE_CLIENT_ID can be found in your Kobble dashboard.
4

Add the right permissions to your manifest file

You need to make sure the permissions array of your manifest.json file contains at least the following permissions:

// manifest.json
{
    "permissions": [
        "storage",
        "identity",
        "*://*.kobble.io/*",
        "tabs",
    ]
    // rest of the file...
}
5

Add the redirect URI of your Chrome Extension into your Kobble Application

  1. Open the Applications tab of your Kobble dashboard.
  2. Click on the application you’re using in your Chrome extension.
  3. Scroll to the Authorized redirect URIs section and click on Edit.
  4. Add the following URI: https://ID.chromiumapp.org/callback where ID is the ID of your Chrome extension.
The ID of your extension can be found on this page chrome://extensions/. Here is more information about how to find your ID. Note that the ID may change if you remove and reload your extension.
6

Start using our components

Unlike for a web application, you don’t have to setup a callback handler.

So we can directly use our components, here’s an example.

import {LoginButton, LogoutButton, SignedIn, SignedOut} from "@kobbleio/react-web-extension";

const Newtab = () => {
        return (
        <div>
            <SignedIn>
                <span>You are logged in</span>
                <LogoutButton>Logout</LogoutButton>
            </SignedIn>

            <SignedOut>
                <span>You are logged out</span>
                <LoginButton>Login</LoginButton>
            </SignedOut>
        </div>
    );
};

export default Newtab;

Hooks

The SDK exposes many hooks that you can use to interact with the authentication state of your application.

useAuth()

The useAuth hook allows you to get the authentication state of the user. Instead of using the kobble client instance, you can directly get the user object from the react context.

import { useAuth } from "@kobbleio/react-web-extension";

const { user, isAuthenticated } = useAuth();

useAuthStateChanged()

The useAuthStateChanged hook allows you to listen for changes in the authentication state of the user.

The callback function will be called with the user object when the user is signed in, and null when the user is signed out.

The callback may be called multiple times. For instance when you refresh the page it will be initially called with a null user and then the User object if authenticated.
import { useAuthStateChanged } from "@kobbleio/react-web-extension";

useAuthStateChanged((user) => {
    // user can be null or a User object
    console.log('Auth state changed', user);
});

useAccessControl()

The useAccessControl hook allows you to check if the user has the required permissions or quotas to access a specific resource.

You must attribute quotas and/or permissions to your Products from your Kobble dashboard for them to work.

Check permissions

import { useAccessControl } from "@kobbleio/react-web-extension";
const { hasPermission } = useAccessControl();

const canGenerateImage = async () => {
    return hasPermission('generate-image');
}

Check remaining quotas

import { useAccessControl } from "@kobbleio/react-web-extension";
const { hasRemainingQuota } = useAccessControl();

const canGenerateImage = async () => {
    return hasRemainingQuota('image-generated');
}

useKobble()

The useKobble hook allows you to get the kobble client instance that exposes various utility methods.

Get user state

Even if you can do it using the Kobble instance we suggest you do it using the useAuth hook explained above.
import { useKobble } from "@kobbleio/react-web-extension";

const { kobble } = useKobble();

const anything = async () => {
    const user = await kobble.getUser();
    const isAuthenticated = await kobble.isAuthenticated();
};

Get access and ID tokens

import { useKobble } from "@kobbleio/react-web-extension";

const { kobble } = useKobble();

const anything = async () => {
    const accessToken = await kobble.getAccessToken();
    const idToken = await kobble.getIdToken();
};

Listen for state changes

The onAuthStateChanged method allows you to listen for changes in the authentication state of the user.

The callback function will be called with the user object when the user is signed in, and null when the user is signed out.

The callback may be called multiple times. For instance when you refresh the page it will be initially called with a null user and then the User object if authenticated.
import { useKobble } from "@kobbleio/react-web-extension";
const { kobble } = useKobble();

kobble.onAuthStateChanged((user) => {
    // user can be null or a User object
    console.log('Auth state changed', user);
});

Components

The SDK exposes a few components that you can use to interact with the authentication state of your application seemlessly.

<SignedIn>

The <SignedIn> component allows you to show content only when the user is signed in.

import { SignedIn, useAuth } from "@kobbleio/react-web-extension";

const { user } = useAuth();

<SignedIn>
    <span>Welcome back, {user.name}</span>
</SignedIn>

<SignedOut>

The <SignedOut> component allows you to show content only when the user is signed out.

import { SignedOut } from "@kobbleio/react-web-extension";

<SignedOut>
    <span>Sign in to access more features</span>
</SignedOut>

<LoginButton>

The <LoginButton> component allows you to show a button that triggers the login flow and redirects the user to your authentication portal.

You can use the component as it or pass it a child to customize it.

Default usage:

import { LoginButton, SignedOut } from "@kobbleio/react-web-extension";

<SignedOut>
    <LoginButton />
</SignedOut>

Custom usage:

import { LoginButton, SignedOut } from "@kobbleio/react-web-extension";

<SignedOut>
    <LoginButton>
        <button className="your-class-or-any-other-attribue">Login</button>
    </LoginButton>
</SignedOut>
The onClick event will automatically get handled by the SDK, don’t pass any handler.

<LogoutButton>

The <LogoutButton> component allows you to show a button that triggers the logout flow.

You can use the component as it or pass it a child to customize it.

Default usage:

import { LogoutButton, SignedIn } from "@kobbleio/react-web-extension";

<SignedIn>
    <LogoutButton />
</SignedIn>

Custom usage:

import { LogoutButton, SignedIn } from "@kobbleio/react-web-extension";

<SignedIn>
    <LogoutButton>
        <button className="your-class-or-any-other-attribue">Logout</button>
    </LogoutButton>
</SignedIn>
The onClick event will automatically get handled by the SDK, don’t pass any handler.

<IsAllowed>

The <IsAllowed> component allows you to show content only when the user has the required permissions or quotas to access a specific resource.

It takes a permission or quota prop that you can use to check if the user has the required permissions or quotas.

Both permission and quota props can be either a string or an array of strings.

import { IsAllowed } from "@kobbleio/react-web-extension";

<IsAllowed permission="generate-image">
    <button>Generate Image</button>
</IsAllowed>
import { IsAllowed } from "@kobbleio/react-web-extension";

<IsAllowed quota="image-generated">
    <button>Generate Image</button>
</IsAllowed>

<IsForbidden>

The <IsForbidden> component allows you to show content only when the user doesn’t have the required permissions or quotas to access a specific resource.

It takes a permission or quota prop that you can use to check if the user doesn’t have the required permissions or quotas.

Both permission and quota props can be either a string or an array of strings.

import { IsForbidden } from "@kobbleio/react-web-extension";

<IsForbidden permission="generate-image">
    <span>Sorry, you don't have the required permissions to generate an image</span>
</IsForbidden>
import { IsForbidden } from "@kobbleio/react-web-extension";

<IsForbidden quota="image-generated">
    <span>Sorry, you've reached the maximum number of images you can generate</span>
</IsForbidden>

The <ProfileLink> component allows you to show a link to the user’s profile of your Customer Portal.

It must take a child that will be used as the link text.

import { ProfileLink, SignedIn } from "@kobbleio/react-web-extension";

this

<SignedIn>
    <ProfileLink>My Profile</ProfileLink>
</SignedIn>

The <PricingLink> component allows you to show a link to the pricing page of your Customer Portal.

It must take a child that will be used as the link text.

import { PricingLink } from "@kobbleio/react-web-extension";

<PricingLink>View Pricing</PricingLink>