Install multiple instances

Multiple instances (brands in same organisation or brands across multiple organisations) can be installed within the same browser page, this method is referred to as a multi-instance install.

This method is useful if you require sending data to two or more sets of data destinations with each set having their own identities, event tracking and configuration.

Installing

Multi-instance install can be achieved by using the script tag installation or via the NPM package.

Script tag

To get org, id, and key for each instance, visit API settings in the Seeka app, ensuring that the correct organisation and brand is selected.

<script>
    // Insert script tag here - Copy from https://seeka.app/setup/sources/script-tag-install
    // In the copied script tag, remove the "SeekaInstall" line and replace it with the below code

    SeekaInstall(
        {
            "instances": [
                // instance / brand 1
                {
                    "org": "", // Org id
                    "id": "", // Instance ID
                    "key": "" // Public key
                },
                // instance / brand 2
                {
                    "org": "", // Org id
                    "id": "", // Instance ID
                    "key": "" // Public key
                }
                // More instances can be added
            ]
        }
    );
</script>

NPM package

Terms

  • scopeKey - A unique identifier for each instance. This is used to access the SDK of a single instance. Usually the ID of the converge instance.
  • scopeDescription - A human friendly name to identify the instance. Usually the name of the brand associated with the converge instance.

The example below installs two different instances and the SDK of each instance are accessible via converge.instances['FirstBrandScope'] and converge.instances['SecondBrandScope'].

import {
  ConvergeSdk,
  TrackingActivityNames,
  ConvergeSdkLogEventLevel,
} from "@seeka-labs/converge";
import { BotDetectionConvergeSdkPlugin } from "@seeka-labs/converge-plugin-botdetection";
import { SnapchatPixelConvergeSdkPlugin } from "@seeka-labs/converge-plugin-snapchat-pixel";
import { SeekaConvergeSdkPlugin } from "@seeka-labs/converge-plugin-seeka";

const instance1 = {
  scopeKey: "FirstBrandScope",
  scopeDescription: "Some text describing first instance",
  key: "(public key instance 1)",
  organisationId: "(Organisation ID instance 1)",
  debug: {
    isEnabled: true,
    minimumLevel: ConvergeSdkLogEventLevel.Verbose,
  },
  tracking: {
    analytics: {
      autoCollection: {
        activityNames: [
          TrackingActivityNames.ViewPage,
          TrackingActivityNames.ViewProduct,
        ],
      },
    },
    defaults: { currencyCode: "USD" },
  },
  plugins: [
    new BotDetectionConvergeSdkPlugin({}),
    new SnapchatPixelConvergeSdkPlugin({ pixelId: "(Snapchat pixel ID)" }),
    new SeekaConvergeSdkPlugin(),
  ],
};
const instance2 = {
  scopeKey: "SecondBrandScope",
  scopeDescription: "Some text describing second instance",
  key: "(public key instance 2)",
  organisationId: "(Organisation ID instance 2)",
  debug: {
    isEnabled: true,
    minimumLevel: ConvergeSdkLogEventLevel.Verbose,
  },
  tracking: {
    analytics: {
      autoCollection: {
        activityNames: [
          TrackingActivityNames.ViewPage,
          TrackingActivityNames.ViewProduct,
        ],
      },
    },
    defaults: { currencyCode: "USD" },
  },
  plugins: [
    new BotDetectionConvergeSdkPlugin({}),
    new SnapchatPixelConvergeSdkPlugin({ pixelId: "(Snapchat pixel ID)" }),
    new SeekaConvergeSdkPlugin(),
  ],
};

const converge = new ScopedConvergeSdk([instance1, instance2]);

Interacting with SDK

For a single instance

Each instance has the full capability and functionality of the SDK when accessed as below.

See methods for a complete reference of the SDK methods.

// Tracks a page view for only the instance with the scopeKey 3323ba69b19e4261a3fbd3f5d998f118
Converge.instances["3323ba69b19e4261a3fbd3f5d998f118"].track.viewPage();

// Toggles dev mode for only the instance with the scopeKey 3323ba69b19e4261a3fbd3f5d998f118
Converge.instances["3323ba69b19e4261a3fbd3f5d998f118"].debug.toggleDevMode();

// Tracks a page view for only the instance with the scopeKey e4d0e807de71404e9b2a6f82bfcec551
Converge.instances["e4d0e807de71404e9b2a6f82bfcec551"].track.viewPage();

// Merges the profile for only the instance with the scopeKey e4d0e807de71404e9b2a6f82bfcec551
Converge.instances["e4d0e807de71404e9b2a6f82bfcec551"].identity.mergeProfile({
  firstName: ["John"],
  lastName: ["Smith"],
  email: ["john.smith@companydomain123.com"],
  phone: ["+61400111222"],
});

For all instances

It is possible to interact with all installed instances with a single method call but only a subset of the SDK functionality can be utilised in this manner.

This is limited to the following operations:

  • Converge.track (all child methods)
  • Converge.debug (all child methods except isEnabled())
  • Converge.identity.mergeProfile()
// Tracks a page view across all instances
Converge.track.viewPage();

// Merges the profile across all instances
Converge.identity.mergeProfile({
  firstName: ["John"],
  lastName: ["Smith"],
  email: ["john.smith@companydomain123.com"],
  phone: ["+61400111222"],
});

// Toggles dev mode for all instances
Converge.debug.toggleDevMode();

Hooks

When hooks are fired, a scope property will be included in the event detail which signals the instance the hook originated from.

  • A converge.sdk.ready.instance hook will be fired for each instance that is installed.
  • A converge.sdk.ready hook will be fired when all instances are ready.