Plugins

A plugin is a package of code hosted by the platform, and used to modify or extend the features of mediarithmics.

Different types of plugins can be integrated inside the platform:

• Activity analyzer. To enrich real-time user tracking data.

• Audience segment external feed. To send data to partner, either:

  • in server-side streams

  • or by showing a pixel to users in the segment

• Display ad renderer. To customize the rendering of display ads

• Email renderer. To customize the rendering of emails

• Attribution engine. To customize the attribution of a marketing goal to different campaigns.

• Email router. To customize the process of sending an email

• Custom action. To launch a custom action in automations

• Integration batch. To manage data imports or exports through the production of a "batch" of multiple items at once, one stage at a time.

• ML Algorithm (Machine Learning Algorithm). To manage the calculation of predictions attached to a user in an event based manner. ML Algorithm is used in conjunction with an ML Function.

• Computed fields. To manage a calculated field in your schema.

A plugin is a piece of logic encapsulated in a web service. It can be developed in many different languages (see available languages in Plugin SDK). It is hosted and monitored directly by the platform which enables event-based triggering and fast access to the data.

Once a plugin is instantiated in the platform it has to listen to an HTTP port for requests coming from the platform. Depending on its type, a plugin has to comply to a specific REST API.

You can use our Plugin SDK to get off-the-shelf endpoint connectivity and accelerate the development of a plugin.

Key concepts

Imagine the following scenario. A developer wants to create an Activity Analyzer plugin to parse real-time navigation data from a site and add information like product code or name taken from an external system.

1. Developer declares a Plugin with the Activity Analyzer Type.

2. Developer creates a Version 1.0.0, and declares two Properties needed by this version: * a string corresponding to the technical configuration file name to retrieve and a boolean asking whether the code will overwrite product name in the activity) * a Layout corresponding to the UI by which end users will set up properties. He then deploys code associated with this Version.

3. Mediarithmics platform automatically creates a new Worker running the code and waiting for activities to enter the system.

4. User goes into the UI and attaches the created Plugin Version 1.0.0 to its site and sets up the properties. A new Instance is created. Each time an activity comes for this site, the Worker will receive a request and will analyze the context and the properties to adapt the logic.

5. User goes into the UI and attaches the same Plugin version 1.0.0 to an app. A new Instance is created with the new properties.

6. End user asks the developer to add a new parameter and adjust the description text of the set up form. The developer will create Version 2.0.0, redeclare old Properties and add the new one, specify a new Layout and deploy new code attached to this version. A new Worker is created by the platform for this version.

7. User adds the updated Plugin version 2.0.0 to the site, and removes the plugin version 1.0.0 from the site. Activities arriving from the site will be analyzed by plugin version 2.0.0, while activities arriving from the app will still be analyzed by plugin version 1.0.0.

Plugin

The top-level abstraction is the declaration of a plugin.

It is attached to a specific organisation, and has a specific type.

It is classified with a group_id and an artifact_id. A group_id is the name of the context (usually a reversed domain name, like com.mediarithmics.creative.display). It can contain lowercase alphanumeric characters, dots, hyphen, and underscore. An artifact_id is the technical name of the plugin (like image-iframe). It can contain lowercase alphanumeric characters, hyphen, and underscore (not dot). Here are some Group/artifact examples:

• com.mediarithmics.creative.display / image-iframe

• com.mediarithmics.creative.display / flash-iframe

• com.mediarithmics.bidding.optimizer / dtlr

• com.mediarithmics.bidding.optimizer / dynamic-filtering-optimizer

• com.mediarithmics.audience.externalfeed / adobe-connector

• etc

Create unique group_id / artifact_id combinations as they'll act as identifiers with versions.

Each plugin type has its own standard for group ids and artifact ids. It will be written in the documentation of the plugin type.

Sample declaration of a plugin

{
  "id": "1100",
  "organisation_id": "1234",
  "plugin_type": "BID_OPTIMIZATION_ENGINE",
  "group_id": "com.company.optimizer",
  "artifact_id": "shiny_algorithm",
  "current_version_id": "1200"
}

Versions

Plugins support versioning. Each version can have a different codebases, layouts, properties, declaration and configuration files. A version can contain three digits and an optional suffix. Exemple : 1.0.0, 1.2.0-rcl

Each plugin can have multiple versions available at the same time.

Workers

To properly scale the processing of your Plugin, mediarithmics platform will deploy the code of your Plugins multiples times on different servers, and do Load balancing between those.

Each time that you create a new version or when scaling is needed, the platform will create a new Worker. In this process, the /init route of the new worker is called for initialization and authentication, then it joins the other workers when /status route responds ready.

Instances

Instances are created on mediarithmics UI when configuring a plugin for a use case. They are linked to a plugin version, property values and a context of execution.

For example:

• A connection to AppNexus is made on a segment, with version 1.0.0 or our AppNexus plugin.

Each time the end user configures the same plugin for different targets, it won't necessarily create a new Worker but it will create a new instance. The code of a plugin should retrieve the instance to adapt to its context.

1. Parse the request to find the Instance associated (the id of the Instance is always in the request body, ex: creative_id for a Display Ad Renderer)

2. Fetch (and cache for future use) the properties associated to this Instance

3. Do the processing according to this Instance configuration (e.g. render the proper Creative)

Note: If you're using NodeJS, the NodeJS Plugins SDK is doing those tasks for you. How the user can configure a new Instance is defined by the Plugin Developer when he creates the Plugin / Plugin Version (see below).

Properties

A plugin version declares properties that will be available in Instances of your plugin.

{
  "technical_name": "provider",
  // Default value if property is writable, 
  // value shared across all instances if not writable
  "value": {
    "value": "mediarithmics"
  },
  // See the list of property type
  "property_type": "STRING",
  // PLUGIN_STATIC | PLUGIN | INSTANCE
  "origin": "PLUGIN_STATIC",
  // If property value can be set in instances of this version
  "writable": false,
  // Set to false
  "deletable": false
}

PLUGIN_STATIC properties

You have to define two PLUGIN_STATIC properties each of your plugin versions : name and provider. The PLUGIN_STATIC origin is reserved for mandatory properties defined by mediarithmics.

// This property defines the provider of the plugin
// This is usually 
// 1. 'mediarithmics' for plugins made by mediarithmcis
// 2. The integrator or the customer name for other plugins
// You can set a different value, but you can't change anything
// else in the property.
{
   technical_name: "provider",
   value: {
     value: "you"
   },
   property_type: "STRING",
   origin: "PLUGIN_STATIC",
   // Always false
   writable: false,
   deletable: false
}

// This property defines the name of the plugin
// You can set a different value, but you can't change anything
// else in the property.
{
   technical_name: "name",
   value: {
    value: "My plugin"
   },
   property_type: "STRING",
   origin: "PLUGIN_STATIC",
   writable: false,
   deletable: false
}

As they are not writable, the value will be the same in all Instances of this version.

PLUGIN properties

You can define custom PLUGIN properties for each of your versions.

// This property's value will be the same across all instances
// as it is not writable
{
    technical_name: 'version_specific_property',
    value: {
        value: 'version_value',
    },
    property_type: 'STRING',
    origin: 'PLUGIN',
    writable: false,
    deletable: false,
}
// This property has a default value of 3
// that can be overriden in instances because writable is true
{
    technical_name: 'number_retries',
    value: {
        value: 3,
    },
    property_type: 'INT',
    origin: 'PLUGIN',
    writable: true,
    deletable: false,
}
// This property points to a data file
// that will store advanced configuration variables in JSON
{
    technical_name: 'technical_configuration',
    value: {
        uri: "",
        last_modified: null
    },
    property_type: 'DATA_FILE',
    origin: 'PLUGIN',
    writable: true,
    deletable: false,
}

For usability, we recommend not having more that 15 PLUGIN properties in your versions. If you do more, please consider using DATA_FILE properties.

INSTANCE properties

You can create properties specific to instances of a plugin version.

POST /v1/visit_analyzer_models/:id/properties

      {
	     "technical_name": "my_instance_property",
	     "value": {
	       "value": ""
	     },
	     "property_type": "STRING",
	     "origin": "INSTANCE",
	     "writable": true,
	     "deletable": true
	   }

In this example, we have already created a visit analyzer instance and the INSTANCE property is created on it.

Property types

Basic property types are:

• DOUBLE: {"value":12.45}

• INT: {"value":12}

• BOOLEAN: {"value":true}

• ASSET for an asset hosted on mediarithmics: {"original_file_name": "cat.png", "asset_id": "1333", "file_path": "/1/public/assets/cat.png"}

• URL: {"url": "https://www.google.com"}

• STRING: {"value":"mystring"}

• DATA_FILE: "value": { "uri": "","last_modified": null }

Some additional property types may be added for specific plugin types. Those property types will be explained in the documentation of each plugin type.

Data files

You define a property of type DATA_FILE to point to a file uploaded in the platform (usually in JSON) containing informations the plugin will use at run time.

You usually use a DATA_FILE property instead of multiple properties :

• To be able to update multiple versions or instances of a plugin at once just by uploading a new version of the file.

• To store a lot of advanced properties

• To store properties that only power users should access

Layouts

Layouts give a plugin developer the ability to customize the new/edit plugin instance screens by grouping properties into categories and choosing the type of field representing each of them. It is bound to a plugin version.