Ayrshare Connect Widget

The Ayrshare Connect widget puts our linking buttons inside your own dashboard. You load one script, drop a slot wherever a network belongs in your layout, and we render a button there that already shows whether the account is connected. Your user clicks it and links the account without leaving your page — at most one popup, the network’s own. You write no popup handling, no OAuth callbacks, no session refresh, and no per-network logic. When a network changes something on their end, the fix ships inside our frames the moment we deploy it; you redeploy nothing.

Which Surface You Want

Surface	Your user sees	White-labelling	Choose it when
Widget — embedded frames (`mount()`)	our buttons inline in your own layout; no popup until the network’s own	Strongest. Your page, your fonts and colours, and your user never leaves it	you have a dashboard with a row per network and want linking to happen in place. Max Pack.
Widget — your own button (`popup()`)	your button, then one popup for the network	Strong. The popup is ours, but it is brief and inherits your appearance	you want your own button and styling, and no frames in your layout. Max Pack.
Hosted linking page (how to)	a page we host, carrying your logo, colours and custom CSS	Weakest. It is our page, and your user leaves yours to use it	you want one link to hand out, or you are onboarding by email. Nothing to build, no Max Pack.

A customer dashboard with Ayrshare Connect tiles for Instagram, TikTok and LinkedIn embedded in a card — Embedded frames: our tiles rendered inside your own layout, one slot per network or one slot for several.

The hosted social linking page showing every available network — Hosted linking page: a page we host, carrying your logo and colours, that your user leaves your app to use.

The two widget rows are one integration, not two. A single init gives you both: mount frames where you want our buttons, and call popup() from your own button everywhere else. They share one session and report on the same handlers.Direct mode is the same popup without our script — for a page with a strict Content-Security-Policy, a server-rendered page, or a native app. There you open and watch the popup yourself.

Add the Script

Pin a version and its hash, or track a channel without one. Never both — an integrity attribute on a moving URL stops working at our next release, because the file it names has legitimately changed.

Pinned version

<script
  src="https://app.ayrshare.com/ayrshare-connect/1.2.0/widget.js"
  integrity="sha384-qQ/of8CnYj26nF9RkQ6qk3D1vvzWesu7mpBK6MFK2D0EmmgRJHfbDmRowFBfltmz"
  crossorigin="anonymous"
></script>

Tracking v1

<script src="https://app.ayrshare.com/ayrshare-connect/v1/widget.js" crossorigin="anonymous"></script>

Path	Caching	`integrity`
`/ayrshare-connect/<version>/widget.js`	immutable, one year	yes — pin it
`/ayrshare-connect/v1/widget.js`	five minutes	no
`/ayrshare-connect/latest/widget.js`	five minutes	no

v1 is the channel to recommend. It picks up fixes but never crosses a breaking change. latest crosses major versions by definition, so it will eventually hand your page a version whose behavior you have not reviewed. Every version’s hash is published in manifest.json, which also names what each channel currently serves:

manifest.json

{
  "versions": {
    "1.2.0": { "integrity": "sha384-qQ/of8CnYj26nF9RkQ6qk3D1vvzWesu7mpBK6MFK2D0EmmgRJHfbDmRowFBfltmz" }
  },
  "latest": "1.2.0",
  "channels": { "v1": "1.2.0", "latest": "1.2.0" }
}

Each bundle also opens with a comment naming its own version, which is the fastest way to tell us what a page is actually running:

/*! ayrshare-connect 1.2.0 */

Content-Security-Policy

If your page sends a Content-Security-Policy, it needs two entries, both naming the host you load the script from:

script-src https://app.ayrshare.com;
frame-src  https://app.ayrshare.com;

That is the whole list. You need no connect-src entry for us — our frames reach our API from inside themselves, not from your page — and no entry for popups, which are top-level windows your policy does not govern. Both entries were measured: removing script-src blocks the script, and removing frame-src blocks the frame.

Start an Instance

session is the only required option. It is called once per instance, not once per mount, and must return your backend’s response to Create a Link Session with mode: "connect" — { sessionId, token, expiresAt } — exactly as it came back.

Your page

const connect = AyrshareConnect.init({
  session: () => fetch("/my-api/ayrshare-session").then(r => r.json()),
  appearance: { "--ayr-connect-accent": "#0B7A6C" },
  maxHeight: 800,
});

Your backend

app.get("/my-api/ayrshare-session", async (req, res) => {
  const response = await fetch("https://api.ayrshare.com/api/profiles/link-sessions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.AYRSHARE_API_KEY}`,
      "Profile-Key": profileKeyFor(req.user),
    },
    body: JSON.stringify({ mode: "connect", origin: "https://app.example.com" }),
  });

  res.json(await response.json());
});

A widget session names no network — it authorizes every network your account permits, and which ones appear is decided per mount, in your page. It does carry an origin, which is the one thing that makes the frames render at all: a frame checks the page embedding it against that value and refuses to render anywhere else.

Create the session on your server. The call needs your API key, and the token it returns signs your user into their User Profile — treat it like a password.

We call session again before the token expires, so the widget keeps working on a page left open all day. A call that rejects, or returns no token, is retried twice more — after 0.5s, then 1s — before we give up and emit error. So one refresh costs at most three calls to your endpoint.

Option	Default	Does
`session`	—	Required. Returns a connect-mode link session.
`appearance`	our defaults	Design tokens, applied inside every frame. See Appearance.
`css`	none	A CSS string applied inside every frame. See Custom CSS.
`maxHeight`	`600`	How tall a frame may grow before it scrolls internally instead.

Mount a Slot

One mount per slot. Ask for one network, several, or everything the session permits — the granularity is yours, so a slot can be a single row in an existing table or one panel holding everything.

connect.mount("#instagram-slot", { network: "instagram" });
connect.mount("#some-slot", { networks: ["facebook", "tiktok", "x"] });
connect.mount("#everything");

const row = connect.mount(document.querySelector("#tall"), { maxHeight: 1200 });
row.unmount();

mount takes a CSS selector or an element, and returns { unmount, element }. It throws if the target matches nothing — which is almost always a slot that does not exist yet, so mount after your markup is in the document. Each mount is one iframe. It reports its own height to us and we resize it to match, so your layout reflows as our content changes; past maxHeight the frame scrolls internally instead of running off your page. The narrowest slot we support is 300px. Network keys are Ayrshare’s own, and the alias spellings work too: instagram and instagramapi both mean instagramApi, and x means twitter. A key that is not a network renders no tile.

Your Own Button

A customer who would rather use their own button than one of our frames calls popup instead. It runs the same flow, on the same session, and reports on the same handlers.

Call it directly inside the click handler, with nothing awaited before it. A browser only permits a popup while it is still processing your user’s click, and that permission does not survive an await. Nothing needs awaiting anyway — the session was created at init.

linkedInButton.addEventListener("click", () => {
  connect.popup({ network: "linkedin" });
});

popup returns { close(), network }, and always returns a handle — including after a blocked popup, where close() does nothing — so your code never has to null-check it before calling close(). Every network works here, including the ones a frame finishes inside its own panel: Facebook shows its hand-off explainer in the popup, Bluesky and X show their credential form, and LinkedIn, Pinterest, YouTube and Google Business go out to the network and come back. It throws synchronously for the three things that are programming errors — no network, a destroyed instance, or a session that has not resolved yet. A blocked popup is not one of them: that emits error with reason: "popupBlocked", because your user did nothing wrong. At most one popup is open at a time. A second call closes the first and reports cancelled with reason: "superseded" on it. A popup one of our frames opened is a different thing and is never touched, so your button cannot cancel a flow running inside a mounted slot.

Whether the session may link a network is the server’s answer, not the script’s. A session scoped to Bluesky that is asked for LinkedIn gets a refusal rendered in the popup and reported as error. The script only checks that a network was named at all.

React

The script is framework-free, so React needs nothing special from us — but four things about its lifecycle are worth getting right the first time. Load the script once, outside your component tree. In Next.js that is next/script in your root layout; in Vite or Create React App it is a tag in index.html. Loading it per component re-runs it on every mount.

ConnectAccounts.jsx

import { useEffect, useRef, useState } from "react";

export function ConnectAccounts() {
  const slot = useRef(null);
  const [linked, setLinked] = useState([]);

  useEffect(() => {
    // Inside the effect, so the ref is attached: mount() throws if its target
    // does not exist yet, which is exactly what happens if you call it during render.
    const connect = window.AyrshareConnect.init({
      session: () => fetch("/my-api/ayrshare-session").then(r => r.json()),
      appearance: { "--ayr-connect-accent": "#0B7A6C" },
    });

    connect.mount(slot.current, { networks: ["instagram", "tiktok", "x"] });

    const stop = connect.on("success", ({ network }) => {
      setLinked(current => [...current, network]);
    });
    // `success` is one of ten events the widget reports. See Events below for
    // the full list, including `state`, which replaces polling.

    // destroy() takes the frames, the message listener and the timers with it.
    // Without this, a route change leaves all three behind.
    return () => {
      stop();
      connect.destroy();
    };
  }, []);

  return <div ref={slot} />;
}

Never reuse an instance after destroy(). A destroyed instance stays destroyed — popup() throws on one, and mount() will not bring it back. Create a new instance in the next effect run, which is what the code above does.

Two consequences of that pattern, neither of them a bug:

In development you will see the session callback fire twice. React’s Strict Mode runs effects mount → unmount → mount, so the instance is created, destroyed and created again. The cleanup above makes that safe; it costs one extra call to your backend in dev and none in production.
Keep the effect’s dependencies stable. An array literal passed straight into mount from a parent render is a new value every time, so an effect that depends on it tears the widget down and rebuilds it on every render. Memoize it, or keep it constant as above.

Events

Subscribe with on, which returns an unsubscribe function. Handlers receive the event payload and the mount it came from; off(name, handler) does the same job when you would rather name the handler.

const stop = connect.on("success", ({ network, displayName }, mount) => {
  refreshRow(network, displayName, mount.element);
});
stop();

connect.on("error", ({ network, code, message }) => report(code, message));
connect.destroy(); // every frame, listener and timer

Ten events. Every one carries a network except ready, and except the one kind of error that is not about a network at all — see error has two sources below.

Event	Fires when	Also carries
`ready`	a frame is mounted and ready	—
`click`	your user clicked a network, in either direction	`action`: `"connect"` or `"unlink"`
`started`	a link attempt is under way	—
`selection`	your user reached a picker or a form	`step`
`success`	the account is connected and saved	`displayName` (omitted when unknown), `refId`
`unlinked`	a connected account was removed, and the removal is saved	—
`error`	the attempt failed	`code`, `message`, `reason`
`cancelled`	your user backed out	`reason`
`closed`	the popup this attempt used has closed	—
`state`	a network’s account state, at mount and on every change	`state`, `since`

Four of them are endings — success, unlinked, error and cancelled — and exactly one arrives per attempt. closed is a lifecycle notice that follows an ending rather than being one. click fires before any linking work starts, so it reports a click that a blocked popup or a dead session goes on to refuse. It is the event to use for your own analytics; started is the one that means an attempt is really running.

Reasons

Event	`reason`	Means
`error`	`popupBlocked`	the browser refused to open the popup
`cancelled`	`popupClosed`	your user closed the window by hand
`cancelled`	`scopesDenied`	your user declined a permission the network asked for
`cancelled`	`userCancelled`	your user backed out, or your code called `handle.close()`
`cancelled`	`superseded`	a second `popup()` call replaced this attempt

`error` Has Two Sources

Only one of them is a link failure, and they carry different fields.

A link error carries network, code and the mount it came from.
A session error — we could not create or refresh your session — carries only message, because nothing was being linked at the time.

Destructure defensively: code and network are undefined on the second kind.

`state` Saves You Polling

state is the data channel rather than a report on an attempt. Every frame emits one per network as it mounts, carrying that network’s current state and the since timestamp it has held it from, and another whenever a state changes — including changes that originate on our side, such as a token dying into relink-required. So you can drive your whole UI from the widget without polling anything. The values are the same enum GET /profiles with include=state returns: linked, unlinked, identityVerificationRequired, restricted, rateLimited, suspended.

Unlinking

Our tiles unlink as well as link. Your user clicks a connected network, confirms, and the account is removed:

click fires with action: "unlink".
unlinked fires once the removal is saved.

An unlink that fails reports error, and one your user backs out of at the confirm step reports cancelled. There is no separate unlink-failed event.

Appearance

A customer’s stylesheet cannot reach inside a cross-origin frame, so styling travels as data we apply within it. Pass appearance to init as CSS custom properties; each one we do not receive keeps our default.

const connect = AyrshareConnect.init({
  session: getSession,
  appearance: {
    "--ayr-connect-font-family": "Inter, system-ui, sans-serif",
    "--ayr-connect-surface-bg": "#111318",
    "--ayr-connect-surface-fg": "#F2F3F7",
    "--ayr-connect-accent": "#0B7A6C",
    "--ayr-connect-accent-fg": "#FFFFFF",
    "--ayr-connect-radius": "12px",
  },
});

Set colors in pairs. A background token with no foreground token beside it is the one way to make this produce something unreadable: set --ayr-connect-surface-bg to a dark value on its own and our default --ayr-connect-surface-fg is still dark navy. Nothing can infer the other half for you.

With no appearance at all, every token holds its default and a frame looks like this:

Three Ayrshare Connect tiles with the default appearance — Default tokens: white surfaces, dark navy text, indigo accent, 8px radius.

Pass a handful of tokens and the same frame takes on your palette. This example turns the surfaces pale blue, deepens the text and accent to match, and rounds the corners a little more:

const connect = AyrshareConnect.init({
  session: getSession,
  appearance: {
    "--ayr-connect-surface-bg": "#EFF6FF",
    "--ayr-connect-border-color": "#BFDBFE",
    "--ayr-connect-surface-fg": "#0F2A5F",
    "--ayr-connect-surface-fg-muted": "#4A6A9A",
    "--ayr-connect-accent": "#1D4ED8",
    "--ayr-connect-radius": "14px",
    "--ayr-connect-spacing": "10px",
  },
});

Three Ayrshare Connect tiles restyled with pale blue surfaces and a deeper blue accent — The same three tiles after the tokens above are applied.

There is one palette and no light/dark preset. Nothing keys on prefers-color-scheme, on purpose — your page’s theme may not match your user’s operating system, and a media query would silently outvote the colors you chose. A dark dashboard is themed by supplying dark values. This token list is a supported contract we keep across versions.

The Tokens

Token	Default
`--ayr-connect-font-family`	`Inter, "Segoe UI", system-ui, -apple-system, sans-serif`
`--ayr-connect-font-size`	`16px`
`--ayr-connect-font-size-sm`	`12px`
`--ayr-connect-label-font-weight`	`600`
`--ayr-connect-status-font-size`	`12px`
`--ayr-connect-status-font-weight`	`600`
`--ayr-connect-surface-bg`	`#FFFFFF`
`--ayr-connect-surface-bg-hover`	`#F7F7F7`
`--ayr-connect-surface-fg`	`#010629`
`--ayr-connect-surface-fg-muted`	`#56596F`
`--ayr-connect-border-color`	`#DDDEE2`
`--ayr-connect-border-width`	`1px`
`--ayr-connect-radius`	`8px`
`--ayr-connect-spacing`	`8px`
`--ayr-connect-accent`	`#4553EE`
`--ayr-connect-accent-fg`	`#FFFFFF`
`--ayr-connect-focus-ring-color`	`#4553EE`
`--ayr-connect-focus-ring-width`	`2px`
`--ayr-connect-disabled-fg`	`#6E7185`
`--ayr-connect-status-radius`	`4px`
`--ayr-connect-status-success-bg`	`#EBFFF8`
`--ayr-connect-status-success-fg`	`#237C5C`
`--ayr-connect-status-warning-bg`	`#FFF7EF`
`--ayr-connect-status-warning-fg`	`#702E00`
`--ayr-connect-status-critical-bg`	`#FFE5E1`
`--ayr-connect-status-critical-fg`	`#AD1902`
`--ayr-connect-status-info-bg`	`#ECF9FF`
`--ayr-connect-status-info-fg`	`#1F6686`
`--ayr-connect-callout-bg`	`#FFF7EF`
`--ayr-connect-callout-fg`	`#702E00`
`--ayr-connect-partner-name`	`""`
`--ayr-connect-icon-size`	`32px`
`--ayr-connect-avatar-size`	`40px`

A value that is not valid CSS for its token is ignored, with a warning in your console, rather than applied. That matters more than it sounds: a unitless 8 for --ayr-connect-spacing is a perfectly innocent string that would invalidate every calculation reading it and collapse the layout, with no error anywhere. Give lengths a unit.

Your Own Name on the Hand-Off Screen

Before we hand your user to a network, we show a short screen naming who they are connecting through. Two hooks let you make that your own, and both are version-stable. --ayr-connect-partner-name sets the label. It is the one token whose value is text, so it has to be quoted as a CSS string — an unquoted value is invalid and renders nothing at all:

AyrshareConnect.init({
  session: getSession,
  appearance: { "--ayr-connect-partner-name": "'Acme Social'" },
  css: "[data-ayr-connect-partner-mark]::after { background-image: url('https://cdn.example.com/mark.svg') }",
});

The logo is not a token. We ship the mark as a positioned, sized element and you fill it with a background-image through css, as above — a token that could fetch an image from inside our document is not something we accept, so the request comes from a rule you wrote rather than from a value you passed us.

[data-ayr-connect-partner-mark] and [data-ayr-connect-partner-name] are the exception to the custom-CSS caveat below: these two selectors are part of the contract and we keep them across versions.

Custom CSS

css takes a string applied inside every frame, for the cases tokens do not cover.

AyrshareConnect.init({ session: getSession, css: "button { letter-spacing: 0.01em }" });

Custom CSS is not supported across versions. Its selectors target our internal markup, which changes between releases — a rule that works today can silently stop matching after any update. The token contract above is the part we keep. Pin a version if you depend on custom CSS.

Popups inherit the instance’s appearance and css exactly as frames do, so your user does not watch our neutral defaults appear halfway through a flow.

Worth Knowing Before You Ship

One session per instance, not one per mount

Fourteen mounts share one token and cost one call to your backend, not fourteen. If you want differently scoped slots — a different allowedSocial on some of them — run a second init with its own session rather than expecting a mount to narrow it.

The frames only render on the origin you declared

Every session carries the origin your page runs on, and a frame compares the page embedding it against that value before rendering anything. A frame embedded somewhere else stays blank and sends no events. There is no allowlist to register and nothing to configure — send the right origin when you create the session.

Height is handled for you, and is not an event

Frames report their height to the script, and the script resizes them. Your layout just reflows. There is no resize event to subscribe to, and nothing to measure on your side.

Requirements

The Max Pack. A widget session is a connect-mode session, and creating one without the Max Pack returns code: 504. Contact support if you need connect mode enabled on an account without it.
An origin on every session — the exact origin your page runs on. Omitting it returns code: 505; a value that is not an https origin, a custom scheme, or http://localhost returns code: 506.
No network on the session. That parameter is what makes a session direct mode instead, and a direct-mode session’s URL is not what the script expects.

Every code above is in the Link Session Errors reference, with the exact message the API returns and what to do about it.

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

Which Surface You Want

Add the Script

Content-Security-Policy

Start an Instance

Mount a Slot

Your Own Button

React

Events

Reasons

`error` Has Two Sources

`state` Saves You Polling

Unlinking

Appearance

The Tokens

Your Own Name on the Hand-Off Screen

Custom CSS

Worth Knowing Before You Ship

Requirements

​Which Surface You Want

​Add the Script

​Content-Security-Policy

​Start an Instance

​Mount a Slot

​Your Own Button

​React

​Events

​Reasons

​error Has Two Sources

​state Saves You Polling

​Unlinking

​Appearance

​The Tokens

​Your Own Name on the Hand-Off Screen

​Custom CSS

​Worth Knowing Before You Ship

​Requirements

Which Surface You Want

Add the Script

Content-Security-Policy

Start an Instance

Mount a Slot

Your Own Button

React

Events

Reasons

`error` Has Two Sources

`state` Saves You Polling

Unlinking

Appearance

The Tokens

Your Own Name on the Hand-Off Screen

Custom CSS

Worth Knowing Before You Ship

Requirements