Embed quickstart

This guide adds the plugin to a page in your app. It takes a few minutes and needs no server changes.

Before you start

Your platform ID. It is public, so it is safe to put in your page.
Approval for each web address (origin) where the plugin will appear, such as https://app.example.com.
The page in your app where the plugin lives, such as https://app.example.com/integrations/branduo. Merchants return there after they approve their plan in Shopify.

1. Add the plugin to your page

Add the loader script, an empty element for the plugin, and one call to BrandConnect.init:

<script
  src="https://connect.branduo.io/loader/v2.0.0/brand-connect.js"
  integrity="sha384-…"
  crossorigin="anonymous"
></script>

<div id="brand-connect"></div>

<script>
  BrandConnect.init({
    container: "#brand-connect",
    platformId: "YOUR-PLATFORM-UUID",
    domain: "brand.com",
  });
</script>

Then:

Replace YOUR-PLATFORM-UUID with the platform ID from Support.
Set domain to the signed-in merchant’s store domain, from your own records. A custom domain (brand.com) or the *.myshopify.com domain both work. Branduo drops the scheme, any path, and www..
Replace sha384-… with the value published at https://connect.branduo.io/loader/v2.0.0/brand-connect.js.sri. The versioned URL never changes, so the hash stays valid until you move to a new version.

That’s the whole integration. The plugin works out the merchant’s stage and shows the right screen.

Option	Required	Description
`container`	Yes	The element, or a selector for it, that the plugin appears in.
`platformId`	Yes	Your platform ID, a UUID.
`domain`	Yes	The merchant’s store domain.
`mode`	No	`"page"` (default) or `"drawer"`.
`onEvent`	No	Called with `{ type: "brand.connect.stage", stage }` when the plugin loads and whenever the stage changes. See Stages.
`onClose`	No	Called when the merchant closes the drawer.

TypeScript types are published at https://connect.branduo.io/loader/v2.0.0/brand-connect.d.ts.

2. Open it in a drawer (optional)

To open the plugin from a button instead of showing it on the page, set mode: "drawer" and call open() on the handle that BrandConnect.init returns:

<button id="partner-with-brands">Partner with brands</button>
<div id="brand-connect"></div>

<script>
  const handle = BrandConnect.init({
    container: "#brand-connect",
    platformId: "YOUR-PLATFORM-UUID",
    domain: "brand.com",
    mode: "drawer",
    onClose: () => console.log("Drawer closed"),
  });

  document
    .getElementById("partner-with-brands")
    .addEventListener("click", () => handle.open());
</script>

The drawer opens from the right, up to 520 pixels wide. It closes with its Close button, a click on the backdrop, or the Escape key. Each of these calls onClose. The handle has three methods:

open(): opens the drawer. It does nothing in page mode.
close(): closes the drawer and calls onClose.
destroy(): removes the plugin and its listeners.

In page mode, the plugin fills the container’s width and grows with its content, starting at 480 pixels tall.

3. Allow Branduo in your security policy

If your app uses a Content Security Policy, allow Branduo:

script-src https://connect.branduo.io;
frame-src https://connect.branduo.io;
child-src https://connect.branduo.io;

Add these values to your existing policy rather than replacing it. The plugin only loads on origins Support approved. An origin includes the protocol and hostname, so https://app.example.com and https://example.com are different. If another site frames your app, ask Support to approve both origins.

4. Bring merchants back after they approve their plan

New merchants install Branduo from the Shopify App Store and approve their plan in Shopify. To send them straight back to your app afterward:

Give Support the page where the plugin lives (see Before you start). It must be on an approved origin.
Sync your merchants’ store domains with Sync platform brands. Branduo uses that list to know which app a merchant came from.

When both are in place, Install and Approve plan open in the same tab, and Branduo returns the merchant to your page with ?branduo_connect=return. The loader removes that parameter from the address bar. In drawer mode, it also reopens the drawer, so call BrandConnect.init on that page load as usual. Without them, those buttons open in a new tab, and the plugin checks again when the merchant comes back to your tab.

Next steps

See what merchants see at each stage. If the plugin does not load, work through Troubleshooting.

Getting started

Embed plugin

Endpoints

Embed quickstart

Before you start

1. Add the plugin to your page

2. Open it in a drawer (optional)

3. Allow Branduo in your security policy

4. Bring merchants back after they approve their plan

Next steps

​Before you start

​1. Add the plugin to your page

​2. Open it in a drawer (optional)

​3. Allow Branduo in your security policy

​4. Bring merchants back after they approve their plan

​Next steps

Before you start

1. Add the plugin to your page

2. Open it in a drawer (optional)

3. Allow Branduo in your security policy

4. Bring merchants back after they approve their plan

Next steps