Getting Started with Topol Plugin

Embedding Topol Plugin takes two steps: create an API token, then add a container element and a short script to your page. Everything else is optional and can be layered on later.

Step 1: Create your API token

Log into your Topol Account, open the API Tokens tab and click + New API Token. The page that opens creates the token that authorizes the Topol Plugin in your application.

The token comes with two keys, shown in the API Keys tab: the Public API key goes into the Plugin configuration in your page, and the Secret key authorizes direct calls to the Topol API and must never be exposed in client-side code.

With the token created, switch to the Configuration tab and add every domain where the Plugin will run to the Allowed domains list.

WARNING

The token only works on the domains listed in its configuration.

Step 2: Add the Plugin to your application

INFO

Topol also offers integration packages if you're using frameworks like React, Vue, or Angular to make setup even easier. Find out more here.

With the API key ready, the Plugin goes into your page in two pieces: a container element and a script that configures and starts the editor.

First, add this HTML where you want the editor to appear. The container needs an explicit width and height, otherwise the editor has no space to render:

<!-- This is the container where the Topol Plugin will load -->
<div id="app" style="position: absolute; width: 100%; height: 100%;"></div>

Next, load the Plugin script and initialize it:

<!-- Load the Topol Plugin script -->
<script
  src="https://v3.email-assets.topol.io/loader/build.js"
  type="text/javascript"
></script>

<!-- Configure and initialize the Topol Plugin -->
<script>
  const TOPOL_OPTIONS = {
    id: "#app", // The div where the editor will appear
    authorize: {
      apiKey: "YOUR_API_KEY", // Replace with your Public API key from step 1
      userId: "UserID", // Any unique ID you assign for the user
    },
    callbacks: {
      onSave: function (json, html) {
        // This function runs when the user saves
        // You can handle the JSON and HTML data here (e.g., save to your server)
      },
    },
  };

  // Start the Topol Plugin with these settings
  TopolPlugin.init(TOPOL_OPTIONS);

  // Optional: Load a template into the editor on start
  fetch("https://tlapi.github.io/topol-editor/templates/1.json")
    .then((response) => response.text())
    .then((template) => {
      TopolPlugin.load(template);
    });
</script>

Important notes:

• The apiKey is the Public API key from Step 1.
• The userId can be any unique string that identifies your user (letters, numbers, _ or -). It determines where that user's images are stored and counts as one unique user for monthly billing. Typically, one userId corresponds to one client of your app, CRM, ESP, etc. Reusing a single userId across several people counts them as one user and gives them a shared image library.
• The example also loads a sample template from a URL. Replace it with your own template, or drop that optional block to start the editor empty.

INFO

Running into trouble while implementing the Topol Plugin? Contact our support team here and we'll help you get it working.