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

# Install the in-app launcher

> For developers: add Juno's launcher script to your product, and sign a short-lived token for each signed-in user on your backend.

The in-app launcher adds a **Learn** button to your own product. On the pages your admin chooses, your signed-in users see the learning that fits that page, and one click opens it in Juno, already signed in. This page is for the developers who install it: a script in your app, and a token route on your backend.

![A sample service desk app on its Automation rules page. Above the Learn button, a For this page list shows three learning items, each with Start](https://mintcdn.com/juno-76d1c392/06xhJJ4nqlFuJ4P8/images/integrations/in-app-launcher.png?fit=max\&auto=format\&n=06xhJJ4nqlFuJ4P8\&q=85\&s=9a133ec7ccd1fceea2563aac75d71de0)

> [!NOTE]
>
> The in-app launcher is in beta. Admins decide where the button shows, and for whom, in [In-app launcher](https://docs.junojourney.com/admin/in-app-launcher.md).

***

## How it works

1. In Juno, an admin writes rules on **Admin** > **Settings** > **In-app launcher**: which pages show the button, for which users, and which learning it opens
2. Your page loads Juno's script. The script calls your `getToken` function, which gets a short-lived token from **your backend**, then asks Juno for this user's rules
3. The button shows on the pages a rule matches. The script matches pages itself, so your page addresses never leave the browser
4. A click opens the learning: your backend signs a sign-in token, and the user lands in Juno, signed in as a learner

Some things to know:

* **Learners only.** New users are created as learners. Someone who is an admin or manager in Juno is asked to sign in to Juno directly.
* **No button when something's wrong.** If your `getToken` or Juno fails or doesn't answer within 3 seconds, the page shows no button, and nothing else on the page changes. The script tries five more times, waiting 2, 4, 8, 16 and 32 seconds in between, so a slow first answer, or a user who signs in within about a minute, still gets the button. A refusal from Juno (see [Troubleshooting](#troubleshooting)) ends it at once, except `429` `rate_limited`.
* **A new tab, or a panel.** Juno opens in its own tab. When your admin sets **Open learning in** to **A side panel on the page**, it opens in a [panel on your page](#open-in-a-panel-on-your-page) instead, still signed in.

***

## Before you start

> [!NOTE]

The launcher signs users in with the same secret as [Portal SSO](https://docs.junojourney.com/integrations/portal-sso.md). Your Juno admin generates it: see [Signing key for the in-app launcher](https://docs.junojourney.com/integrations/in-app-launcher-signing-key.md).

**Install** has everything to copy: the code for your app, the script tag, your site key, and the Content Security Policy lines.

![The Install section: the app code, the script tag, the script URL and site key, the Content Security Policy lines, and the token instructions, each with Copy](https://mintcdn.com/juno-76d1c392/fmH0wspOpEc0LZXE/images/admin/in-app-launcher-install.png?fit=max\&auto=format\&n=fmH0wspOpEc0LZXE\&q=85\&s=42131e4ec6b740ef6dd1bd8a10b2da1d)

***

## Step 1: Sign tokens on your backend

Add a route to your backend that signs a token for whoever is signed in. Shape it the way your API already works: Juno only needs the token, which your `getToken` function returns in Step 2. Your Portal SSO secret stays on your backend and never reaches the browser.

* The script asks for two kinds of token: `launcher` on page load, and `signin` when the user clicks
* Protect the route like your other API routes: your sign-in session, and your usual protection against cross-site requests
* Don't let anything cache the answer: each token works once

Tokens are HS256-signed JWTs in the Portal SSO format, with your secret's key ID in the `kid` header:

| Claim | Token | Rule |
| - | - | - |
| `purpose` | Both | `launcher` or `signin` |
| `sub` | Both | Your user ID. Stable, at most 256 characters. Juno links the learner to it |
| `aud` | Both | Your tenant ID in Juno, as in Portal SSO |
| `iss` | Both | A stable name for your product, such as `acme-app` |
| `jti` | Both | Unique per token. Each token works once |
| `iat`, `exp` | Both | `exp` at most 300 seconds after `iat`. `iat` at most 60 seconds in the future |
| `locale` | Both, optional | The user's language, such as `en-US` (`en_US` works too). Rules can target it: a rule for `en` covers `en-US`, `en-GB`, and the rest |
| `attrs` | Both, optional | Fields of yours that rules can target, such as `{ "role": "agent", "plans": ["pro", "team"] }`. On page-load tokens: at most 50, each key a letter followed by up to 63 letters, digits, `_`, `.`, or `-`. A value is a string (up to 256 characters), a number, a boolean, a list of up to 100 of those, or `null` for no value. Send a date as an ISO 8601 string, such as `"2027-01-31"`. No value or list item may be an email address. Sign-in doesn't use `attrs` |
| `email` | Sign-in | The user's email |
| `email_verified` | Sign-in | `true` only if you've verified this address. Juno refuses `false` |
| `name` | Sign-in, optional | The user's display name |
| `attributes` | Sign-in, optional | The learner's profile, as in a [Portal SSO token](https://docs.junojourney.com/integrations/portal-sso.md#map-attributes), such as `{ "department": "Support", "plan": "pro" }`. Juno writes them onto the learner at every sign-in, the way your admin maps them. A value Juno can't write is skipped, and the sign-in goes on |

A page-load token carries no email: Juno refuses a `launcher` token with `email` or `name`, or with an email address in `attrs`, and the email reaches Juno only when the user clicks. `attrs` only decide which rules apply, and Juno doesn't copy them onto the learner. Each key shows up for your admin under **Learner attributes** in the launcher's settings the first time a page loads with it, and rules can then target it. To fill in the learner's profile for reports and groups, send `attributes` on the sign-in token too: your admin maps them to Juno fields and custom attributes, as for Portal SSO.

```ts node:crypto theme={null}
import { Buffer } from "node:buffer";
import { createHmac, randomUUID } from "node:crypto";

type Purpose = "launcher" | "signin";

interface SignedInUser {
  id: string;
  email: string;
  emailVerified: boolean;
  name?: string;
  locale?: string;
  role: string;
  plan: string;
}

const TENANT_ID = process.env.JUNO_TENANT_ID!; // the aud claim
const KEY_ID = process.env.JUNO_PORTAL_SSO_KID!; // the kid header
const SECRET = process.env.JUNO_PORTAL_SSO_SECRET!; // stays on your backend

const base64Url = (value: object): string => Buffer.from(JSON.stringify(value)).toString("base64url");

export function signJunoToken(purpose: Purpose, user: SignedInUser): string {
  const iat = Math.floor(Date.now() / 1000);
  const claims = {
    purpose,
    sub: user.id,
    iss: "acme-app",
    aud: TENANT_ID,
    iat,
    exp: iat + 120, // at most 300 seconds
    jti: randomUUID(), // each token works once
    locale: user.locale,
    attrs: { role: user.role, plan: user.plan }, // never an email
    // Only the click's sign-in token says who the user is. name is optional.
    ...(purpose === "signin" ? { email: user.email, email_verified: user.emailVerified } : {}),
    ...(purpose === "signin" && user.name ? { name: user.name } : {}),
  };
  const signingInput = `${base64Url({ alg: "HS256", typ: "JWT", kid: KEY_ID })}.${base64Url(claims)}`;
  const signature = createHmac("sha256", SECRET).update(signingInput).digest("base64url");
  return `${signingInput}.${signature}`;
}
```

```ts jsonwebtoken theme={null}
// npm install jsonwebtoken
import { randomUUID } from "node:crypto";
import jwt from "jsonwebtoken";

// SignedInUser: the same fields as in the node:crypto tab.
export function signJunoToken(purpose: "launcher" | "signin", user: SignedInUser): string {
  const claims = {
    purpose,
    sub: user.id,
    iss: "acme-app",
    aud: process.env.JUNO_TENANT_ID!,
    jti: randomUUID(),
    locale: user.locale,
    attrs: { role: user.role, plan: user.plan },
    ...(purpose === "signin" ? { email: user.email, email_verified: user.emailVerified } : {}),
    ...(purpose === "signin" && user.name ? { name: user.name } : {}),
  };
  return jwt.sign(claims, process.env.JUNO_PORTAL_SSO_SECRET!, {
    algorithm: "HS256",
    expiresIn: 120,
    keyid: process.env.JUNO_PORTAL_SSO_KID!,
  });
}
```

Then the route that returns it. Any path, method, and answer shape your app prefers works:

```ts Express route theme={null}
app.post("/api/juno/token", requireSignedIn, (req, res) => {
  // Your usual protection against cross-site requests, for example a header only your app sends.
  if (req.get("X-Juno-Request") !== "1") {
    return res.status(403).end();
  }
  const { purpose } = req.body;
  if (purpose !== "launcher" && purpose !== "signin") {
    return res.status(400).end();
  }
  res.set("Cache-Control", "no-store").json({ token: signJunoToken(purpose, req.user) });
});
```

***

## Step 2: Add the script

In your app's code, tell the launcher your site key and how to get a token. Then add Juno's script to your pages. Copy both from **Install**: they carry your site key and Juno's address.

```js App code theme={null}
// In your app's bundle, while the page loads (before DOMContentLoaded).
window.JunoLauncherConfig = {
  site: "SITE_KEY",
  // Required: get a fresh token from your backend for this purpose, and return the token string.
  getToken: async (purpose) => {
    const response = await fetch("/api/juno/token", {
      method: "POST",
      headers: { "Content-Type": "application/json", "X-Juno-Request": "1" },
      body: JSON.stringify({ purpose }),
    });
    if (!response.ok) {
      throw new Error(`token route answered ${response.status}`);
    }
    return (await response.json()).token;
  },
  ready(launcher) {
    // The launcher is up for this user. See "JavaScript API" below.
  },
};
```

```html Tag theme={null}
<script async src="https://api-prod.the-juno.com/v1/launcher.js"
        crossorigin="anonymous" referrerpolicy="no-referrer"></script>
```

* `getToken` gets `"launcher"` or `"signin"` and returns a promise of the token string. If it rejects, or returns anything else, there's no button, and the browser console says why.
* **Apps with their own menu entry for learning:** set `launcher: "none"` for no corner button, then call `open()` from your menu.
* `referrerpolicy="no-referrer"` keeps your page's address out of the request for the script.

Set `JunoLauncherConfig` in your bundle rather than an inline script, so a strict Content Security Policy needs no `'unsafe-inline'`.

***

## Show it to some users only

If only some of your users get the launcher (say admins, or one plan), load the script for them alone. Your other users load nothing, and neither your token route nor Juno hears from them. Rules in Juno can also target `attrs`, but then every user loads the script.

```tsx React theme={null}
import { useEffect } from "react";

const JUNO_SCRIPT = "https://api-prod.the-juno.com/v1/launcher.js";

declare global {
  interface Window {
    JunoLauncherConfig?: { site: string; getToken: (purpose: "launcher" | "signin") => Promise<string> };
    JunoLauncher?: { shutdown(): void };
  }
}

export function JunoLauncher({ enabled }: { enabled: boolean }) {
  useEffect(() => {
    if (!enabled) return;
    window.JunoLauncherConfig = { site: "SITE_KEY", getToken: fetchJunoToken }; // your call to your backend
    const script = document.createElement("script");
    Object.assign(script, { src: JUNO_SCRIPT, async: true, crossOrigin: "anonymous", referrerPolicy: "no-referrer" });
    document.head.append(script);
    return () => {
      window.JunoLauncher?.shutdown();
      script.remove();
      delete window.JunoLauncherConfig; // a script still loading then starts nothing
    };
  }, [enabled]);
  return null;
}

// <JunoLauncher enabled={user.isAdmin || user.plan === "premium"} />
```

`shutdown()` removes the button and forgets the user, so the next user who should get the launcher starts fresh, without a page reload. A page always runs one launcher, even when the script loads twice. Deleting `JunoLauncherConfig` covers a script still on its way when the user leaves: removing its tag doesn't stop it, but with no config it starts nothing.

***

## Open in a panel on your page

When your admin sets **Open learning in** to **A side panel on the page**, a click opens the learning in a panel on your page, so your users learn without leaving your product. Your install stays the same, apart from one Content Security Policy line.

* **Where it opens.** A full-height panel on the side of the page, full screen on phones. Its header names what the panel shows, goes back to the list when the learning was picked from it, opens the learning it was opened on in a new tab, or closes the panel. Your page keeps working beside it.
* **Only the learning.** The panel shows learning, without Juno's own menu or the rest of Juno. From a course, video or lesson, **All my learning** opens the full list, still in the panel, and the header follows the user to whatever they open next.
* **As wide as the user wants.** They drag the panel's inner edge, or focus it and use the arrow keys, between 360 pixels and 960 pixels or 70% of the window, whichever is less. The browser keeps the width for the next panel in one `localStorage` key on your site, `juno-launcher-panel-width`.
* **Signed in while it's open.** The panel signs the user in with a fresh sign-in token from your `getToken`, and no session stays in the browser after it closes, so the next person on a shared computer starts signed out.
* **Progress shows on your page.** Each row in the list shows the progress Juno saved for that learning: a video's watched share, a course's share of finished sections, or completed. While the panel is open, its header follows along, and the button shows a ring with the share done of the learning the user left unfinished.
* **Learning in order.** When your admin sets a page's learning to be taken in order, the list shows the next item once the user finishes the one before, as Step 2 of 3. It updates as soon as they finish, with no reload, and in a new tab once they come back to yours.
* **Progress reaches your app.** As the user learns, `on("progress")` tells your page, for example to unlock a feature once a course is done. Progress is saved in Juno either way.
* **Your Content Security Policy** needs `frame-src` for your Juno address (see below).

If your Juno account protects its uploaded files, videos, images, and documents inside the panel need Chrome or Edge 114 or later, Firefox 141 or later, or Safari 26.2 or later. In older browsers, the panel's new-tab button opens the learning with everything in it.

***

## Content Security Policy

If your app sends a Content Security Policy, add the lines from **Install**. They allow Juno's script and its requests:

```text theme={null}
script-src  https://api-prod.the-juno.com
connect-src https://api-prod.the-juno.com
```

With [panel mode](#open-in-a-panel-on-your-page) on, **Install** also shows a `frame-src` line for your Juno address:

```text theme={null}
frame-src   https://acme.the-juno.com
```

A click that opens a new tab signs the user in with a form post: it posts to `https://api-prod.the-juno.com` and lands on your Juno address, such as `https://acme.the-juno.com`. If your policy limits `form-action`, add both hosts to it for the fastest sign-in. If you don't, a click still works: it opens a Juno page that signs the user in, a moment slower.

***

## JavaScript API

Once the launcher is up for a user, `window.JunoLauncher` has a small API. Your `ready(launcher)` gets it, and so does a `juno:ready` event on `document` (as `event.detail`). Neither fires when this user gets no button.

| Call | What it does |
| - | - |
| `open({ placement })` | Opens Juno as a click on the button would. Call it from a user's click, or the browser blocks the new tab. `placement` is a rule's ID; without it, the user lands on the default target in Juno |
| `hide()` / `show()` | Hides or shows the button |
| `shutdown()` | For your logout: removes the button and forgets the user |
| `on("notification", fn)` | Calls `fn` with the current notification (or `null`), now and whenever it changes. Returns a function that stops it |
| `on("open", fn)` | Calls `fn({ placement })` each time Juno opens |
| `on("progress", fn)` | Panel mode only. Calls `fn({ placement, unitId, status, percent })` each time Juno saves progress: `status` is `started` or `completed`; `percent`, when Juno knows it, is how much of a video was watched, or 100 |

***

## Troubleshooting

When there's no button, the browser console says why and what to fix, in a line starting with `[Juno launcher]`. Juno's own refusals also show in the network tab, as the answer to `/v1/resolve`:

| You see | Fix |
| - | - |
| `no getToken` or `no site key` | Set `window.JunoLauncherConfig` in your bundle, while the page loads |
| `getToken failed: …` | Your `getToken` rejected, with your own error after the colon. Is the user signed in? |
| `getToken returned an object, not the token string` | Return the token itself, for example `response.data.token` |
| `404` `unknown_site` | Check the site key in **Install** |
| `403` `origin_not_allowed` | Ask Juno support to add your page's address, for example `https://app.acme.com`, to **Allowed origins** |
| `401` `invalid_token` | Check that Portal SSO is switched on, the secret and `kid`, the claims above, and that `exp` is at most 300 seconds after `iat` |
| `401` `invalid_attrs` | Fix `attrs` as the claims table says: at most 50, keys like `plan` or `team.size`, lists of up to 100 with no lists or objects inside, no email addresses |
| `401` `aud_mismatch` | `aud` must be your tenant ID in Juno |
| `401` `replayed_token` | Sign a fresh token for every request: each `jti` works once |
| `204` | The launcher is off for your organization. An admin turns it on in **In-app launcher** |
| No error, and no button on this page | No rule shows the button on this page for this user. Your admin can check it in the **Test box** |
| A click opens "This link is for learners" | This person is an admin or manager in Juno. They sign in to Juno directly |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.