Deployment

Create the plugin and its version

If plugin doesn't already exist, we'll create it with its first version.

Declare the plugin

POST https://api.mediarithmics.com/v1/plugins

Request Body

Name	Type	Description
artifact_id	string	Follow the standards of your plugin type documentation
group_id	string	Follow the standards of your plugin type documentation
plugin_type	string	Enum ACTIVITY_ANALYZER DISPLAY_AD_RENDERER AUDIENCE_SEGMENT_EXTERNAL_FEED EMAIL_ROUTER EMAIL_TEMPLATE_RENDERER ATTRIBUTION_PROCESSOR SCENARIO_CUSTOM_ACTION
organisation_id	string	1 for generic plugins, or the id of the client's organisation if it's dedicated to one client

200

{
  "status": "ok",
  "data": {
    "id": "1001",
    "organisation_id": "1234",
    "plugin_type": "BID_OPTIMIZATION_ENGINE",
    "group_id": "com.company.optimizer",
    "artifact_id": "shiny_algorithm",
    "current_version_id": null
  }
}

You can retrieve a specific plugin information or check your plugin with

Check your plugin

GET https://api.mediarithmics.com/v1/plugins/:plugin_id

Path Parameters

Name	Type	Description
plugin_id	string	The id of the plugin to retrieve

200

Declare a version

POST https://api.mediarithmics.com/v1/plugins/:plugin_id/versions

While creating the new version, you'll have to define the properties you need for your code to run. Usually, you have already written those properties on your test files, do not hesitate to reuse it but do not forget to remove the default values.

Path Parameters

Name	Type	Description
plugin_id	integer	The ID of your plugin

Request Body

Name	Type	Description
plugin_properties	array	The properties of your plugin. Note that "provider" and "name" properties are mandatory. Check the Property object below for format.
version_id	string	1.0.0, 1.2.0, 1.2.0-rcl A version can contain three digits and an optional suffix

200

Property type objects

Here are the attributes for Property type objects:

Attribute	Type	Description
deletable	boolean	Whether the property can be deleted.
writable	boolean	Whether the property can be overwritten.
origin	string	Three possible values: PLUGIN_STATIC. The value is bound to the plugin version and can contains the name of the plugin version, its provider, ... PLUGIN. These properties are copied on each instance and are usually used as parameters in runtime. INSTANCE. Properties with this level can be set on a single instance without affecting other instances. They won't be created automatically.
property_type	string	Defines the format of the value object: DOUBLE INT BOOLEAN ASSET (deprecated) ASSET_FILE ASSET_FOLDER DATA_FILE URL STRING AD_LAYOUT STYLE_SHEET PIXEL_TAG RECOMMENDER NATIVE_DATA (deprecated) NATIVE_TITLE (deprecated) NATIVE_IMAGE (deprecated)
value	object	The default value for the property. The attributes for this object are related to the property_type. See below.
technical_name	string	Unique identifier for the property.

Values format according to property_type

DOUBLE

"value": {
  "value": 12.45
}

INT

"value": {
  "value": 12
}

BOOLEAN

"value": {
  "value": true
}

ASSET (deprecated)

"value": {
  "original_file_name": "cat.png",
  "asset_id": "1333",
  "file_path": "/1/public/assets/cat.png"
}

ASSET_FILE

"value": {
  "original_name": "cat.png",
  "asset_id": "1333",
  "path": "/1/public/assets/cat.png"
}

ASSET_FOLDER

"value": {
  "original_name": "cat.png",
  "asset_id": "1333",
  "path": "/1/public/assets/cat.png"
}

DATA_FILE

"value": {
  "uri": "mics://data_file/tenants/1234/bid_optimizer/shiny/default.conf",
  "last_modified": null
}

URL

"value": {
  "url": "https://www.google.com"
}

STRING

"value": {
  "value": "iframe"
}

AD_LAYOUT

"value": {
  "id": "12",
  "version": "34"
}

STYLE_SHEET

"value": {
  "id": "12",
  "version": "34"
}

PIXEL_TAG

"value": {
  "value": "https://impfr.tradedoubler.com/imp?[...]"
}

RECOMMENDER

"value": {
  "recommender_id": "1"
}

NATIVE_IMAGE (deprecated)

"value": {
  "required_display": true,
  "height": 300,
  "width": 600,
  "type": 1, // We are using the OpenRTB Dynamic Native Ads API 1.2 referential here
  "original_file_name": "cat.png",
  "asset_id": "1333",
  "file_path": "/1/public/assets/cat.png"
}

Note about require_display: when set to true, it means that this content will always be displayed for all impressions. false means that it can be discarded for some impressions.

NATIVE_TITLE (deprecated)

"value": {
  "required_display": true,
  "value": "Everything is awesome!"
}

NATIVE_DATA (deprecated)

"value": {
  "required_display": true,
  "type": 1, // We are using the OpenRTB Dynamic Native Ads API 1.2 referential here
  "value": "5 Stars"
}

Elements associated with your version

Retrieve properties

GET https://api.mediarithmics.com/v1/plugins/:plugin_id/versions/:version_id/properties

Path Parameters

Name	Type	Description
version_id	integer	The ID of your version
plugin_id	integer	The ID of your plugin

200

{
    "status": "ok",
    "data": [
        {
            "technical_name": "segment_name",
            "value": {
                "value": ""
            },
            "property_type": "STRING",
            "origin": "PLUGIN",
            "writable": true,
            "deletable": false
        },
        {
            "technical_name": "segment_description",
            "value": {
                "value": ""
            },
            "property_type": "STRING",
            "origin": "PLUGIN",
            "writable": true,
            "deletable": false
        },
        {
            "technical_name": "customer_user_identifier",
            "value": {
                "value": ""
            },
            "property_type": "STRING",
            "origin": "PLUGIN",
            "writable": true,
            "deletable": false
        },
        {
            "technical_name": "provider",
            "value": {
                "value": "mediarithmics"
            },
            "property_type": "STRING",
            "origin": "PLUGIN_STATIC",
            "writable": false,
            "deletable": false
        },
        {
            "technical_name": "name",
            "value": {
                "value": "Beeswax Audience Feed"
            },
            "property_type": "STRING",
            "origin": "PLUGIN_STATIC",
            "writable": false,
            "deletable": false
        }
    ],
    "count": 5
}

Upload a configuration file

PUT https://api.mediarithmics.com/v1/plugins/:plugin_id/versions/:version_id/configuration_file/technical_name=:technical_name

Uploads or updates a configuration file

Path Parameters

Name	Type	Description
plugin_id	integer	The ID of your plugin
version_id	integer	The ID of your version
technical_name	string	File name

Request Body

Name	Type	Description
body	string	The file needs to be sent as the request body in binary format

200

External services

If your code calls external APIs to retrieve/push data from/to external systems (CRMs, Open APIs / recommendation engines / etc..), you'll need to whitelist them.

Check external services

GET https://api.mediarithmics.com/v1/plugins/:pluginId/versions/:versionId/external_services

Path Parameters

Name	Type	Description
plugin_id	string	The ID of your plugin
version_id	string	The ID of your version

200

{
    "status": "ok",
    "data": [
        {
            "id": "92",
            "url": "https://my.api.domain.com/",
            "technical_name": "technical_name",
            "enabled": true,
            "auth_token": null
        }
    ],
    "count": 1
}

Add an external service

POST https://api.mediarithmics.com/v1/plugins/:pluginId/versions/:versionId/external_services

Path Parameters

Name	Type	Description
plugin_id	string	The ID of your plugin
version_id	string	The ID of your version

Request Body

Name	Type	Description
technical_name	string	deprecated: Just enter any random string value. We keep this field for legacy reasons and we'll drop it in coming API changes.
url	string	Host of your service. Ex: https://graph.facebook.com

200

{
    "status": "ok",
    "data": {
        "id": "93",
        "url": "my.url.domain.com",
        "technical_name": "technical_name",
        "enabled": false,
        "auth_token": null
    }
}

As you'll see in the response, your service may not be enabled. mediarithmics needs to enable each host if it's the first time it is added as an external service. Contact your Account manager with the id of the external service that you wish to enable.

Deploy your code

Setup the build

This step is getting a rework. Stay tuned! You can contact your Account manager for additional information on how to build your code before deploying it into the platform.

Deploy a build

POST https://api.mediarithmics.com/v1/plugins/:pluginId/versions/:versionId/containers/action

Path Parameters

Name	Type	Description
plugin_id	integer	The ID of your plugin
version_id	integer	The ID of your version

Headers

Name	Type	Description
Content-Type	string	application/json

Request Body

Name	Type	Description
target_build_tag	string	The build tag you retrieved after your build.
action	string	DEPLOY_PLUGIN for new versions UPGRADE_ALL_CONTAINERS to update the code of an existing version

200

The deployment can take from 5 to 10 minutes.

Check deployment status

GET https://api.mediarithmics.com/v1/plugins/:pluginId/versions/:versionId/containers?organisation_id=:organisationId

Path Parameters

Name	Type	Description
plugin_id	integer	The ID of your plugin
version_id	integer	The ID of your version
organisation_id	interger	The ID of the plugin's organisation

Headers

Name	Type	Description
Content-Type	string	application/json

200

{
    "status": "ok",
    "data": [
        {
            "name": "XXX",
            "running_containers": [
                {
                    "container": "PLUGIN-MANAGER-COM-CONTAINER_REFERENCE-1.0.0-BUILD-XXX-DEPLOY-XXX"
                }
            ]
        },
    ...
    ],
     "count": 1,
     "total": 1,
     "first_result": 0,
     "max_results": 1
}

Updating a plugin

When to create a new version

You want to create a new version:

• To edit properties.

• To let already added plugins keep their existing behavior.

For example, you won't create a new version if you fix something in the code, or change a delay in a configuration file. But you'll create a new version if the user should enter a new property value or if your code changes so that existing plugins shouldn't use it.

What to do when creating a new version

When creating a new version, you'll have to:

• Redeclare properties, changed or not

• Reupload your configuration files, changed or not

• Redeclare external services, changed or not. Ensure they are enabled.

• Redeploy your code. Think about updating the version number in the build definition.

• Redeclare the layouts

What to do when updating the code of a version

You can update	You can't update
Configuration files	Properties
External services
Code
Layouts