Embed

Integration Guide

Embed an Activoice campaign on any website in minutes

The Activoice embed lets you add a campaign widget directly on your own website. Visitors can participate in the campaign without ever leaving your page — all you need is a small snippet of HTML.

How it works

The embed loads your campaign inside an <iframe> that automatically resizes to match its content. A lightweight JavaScript loader (loader.js) manages the lifecycle: it shows a spinner while the campaign loads, then hands off control to the iframe.

Quick start

Add the loader script

Paste the following tag inside the <head> of your page. You will find the exact URL in the backoffice, on the campaign's Embed panel.

<head>
  <script src="https://app.activoice.org/embed/v1/loader.js"></script>
</head>

Add a container

Place an empty <div> wherever you want the campaign to appear:

<div id="av-embed-container"></div>

Initialize the embed

Call Activoice.init() with your campaign ID:

<script>
window.Activoice.init({
  container: '#av-embed-container',
  campaignId: 'my-campaign-slug',
})
</script>

That's it. The complete snippet looks like this:

index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <script src="https://app.activoice.org/embed/v1/loader.js"></script>
</head>
<body>
  <div id="av-embed-container"></div>

  <script>
  window.Activoice.init({
    container: '#av-embed-container',
    campaignId: 'my-campaign-slug',
  })
  </script>
</body>
</html>

Copy-paste ready snippets are available directly from the backoffice: open a campaign, then click Embed in the top-right actions menu.

Customizing the spinner color

By default the loading spinner uses Activoice's brand yellow (#fed13a). Match it to your site's colors with embedOptions.spinnerColor:

<script>
window.Activoice.init({
  container: '#av-embed-container',
  campaignId: 'my-campaign-slug',
  embedOptions: {
    spinnerColor: '#0057ff',
  },
})
</script>

Choosing where to start the campaign flow

By default, visitors land directly on the action steps (the "go" page). If your campaign has a dedicated landing page you want to show first, set initialPage to 'landing':

<script>
window.Activoice.init({
  container: '#av-embed-container',
  campaignId: 'my-campaign-slug',
  embedOptions: {
    initialPage: 'landing',
  },
})
</script>

Value	Behavior
`'steps'` (default)	Opens directly on the action step
`'landing'`	Shows the campaign landing page first

Controlling the iframe height

The embed resizes automatically to match its content. In some layouts — for example inside a full-height sidebar or a fixed panel — you may want the iframe to fill its container instead:

<div id="av-embed-container" style="height: 100vh;"></div>

<script>
window.Activoice.init({
  container: '#av-embed-container',
  campaignId: 'my-campaign-slug',
  embedOptions: {
    displayMode: 'fullHeight',
  },
})
</script>

Value	Behavior
`'inline'` (default)	Height set in pixels, updated on each content resize
`'fullHeight'`	`height: 100%` is applied; the container controls the height

Control UI appearance

These flags control visible UI elements inside the embedded campaign:

<script>
window.Activoice.init({
  container: '#av-embed-container',
  campaignId: 'my-campaign-slug',
  embedOptions: {
    withToolbar: true,
    withBackground: true,
    withPadding: true,
  },
})
</script>

Option	Default	Effect
`withToolbar`	`false`	Shows the navigation toolbar (back button, step indicator)
`withBackground`	`false`	Applies the campaign's background color to the iframe
`withPadding`	`false`	Adds horizontal padding to the content area

These options default to false so the embed looks clean and seamless by default. Enable them when you want the embed to look closer to the standalone campaign page.

Embedding multiple campaigns on the same page

Call Activoice.init() once per container. Each embed is independent:

<div id="campaign-a"></div>
<div id="campaign-b"></div>

<script>
window.Activoice.init({
  container: '#campaign-a',
  campaignId: 'climate-action',
})

window.Activoice.init({
  container: '#campaign-b',
  campaignId: 'housing-rights',
})
</script>

Overriding campaign recipients

campaignOverrides lets you replace the recipients defined in the backoffice with your own data. This is useful when recipient data comes from an external CRM or changes dynamically.

Global recipients override

Set recipients at the root of campaignOverrides to apply the same recipients to all interpellations at once:

<script>
window.Activoice.init({
  container: '#av-embed-container',
  campaignId: 'my-campaign-slug',
  campaignOverrides: {
    recipients: [
      {
        first_name: 'Alice',
        last_name: 'Smith',
        email: 'alice.smith@example.com',
        display_title: 'Minister of Ecological Transition',
      },
      {
        first_name: 'Bob',
        last_name: 'Jones',
        email: 'bob.jones@example.com',
        display_title: 'Secretary of State for Housing',
      },
    ],
  },
})
</script>

Per-interpellation recipients override

Target a specific interpellation by its ID to override only its recipients. Per-interpellation overrides take priority over the root-level recipients:

<script>
window.Activoice.init({
  container: '#av-embed-container',
  campaignId: 'my-campaign-slug',
  campaignOverrides: {
    recipients: [
      { first_name: 'Alice', last_name: 'Smith', email: 'alice@example.com' },
    ],
    interpellations: [
      {
        id: 'interpellation-uuid',
        recipients: [
          {
            first_name: 'Charlie',
            last_name: 'Durand',
            email: 'charlie.durand@example.com',
            display_title: 'Deputy Mayor',
          },
        ],
      },
    ],
  },
})
</script>

In this example, the interpellation with ID 'interpellation-uuid' receives Charlie as its recipient, while all other interpellations receive Alice.

See the API Reference for the full list of recipient fields and the resolution order.

Campaign Configuration

Learn how to configure and publish campaigns in Activoice

API Reference

Complete reference for the Activoice embed configuration