Creation & Deployment

Summary

Please follow the next steps to Create & Deploy a new plugin:

1. Create a plugin

2. Create a version

3. Add configuration file(s)

4. Add external services

5. Deploy your code

6. Deploy you build

7. Check deployment status

Create a plugin

Via UI

To create a new plugin:

1. Click New Plugin.

2. Configure the following parameters:

Parameters	Description
Plugin Type	Must be one of the following enums: ACTIVITY_ANALYZER ATTRIBUTION_PROCESSOR AUDIENCE_SEGMENT_EXTERNAL_FEED AUDIENCE_SEGMENT_TAG_FEED COMPUTED_FIELD_FUNCTION DISPLAY_AD_RENDERER ML_FUNCTION SCENARIO_CUSTOM_ACTION
Organisation	Defines plugin availability. Use 1 or 100 to make the plugin accessible to all organisations. Otherwise, it will be available only within the specified organisation and its sub-organisations.
Group Id	Used to categorize plugins, typically based on customer and type. Example: com.mycustomer.plugintype for a customer-specific plugin. com.mediarithmics.plugintype for a shared plugin.
Artifact Id	A unique identifier for your plugin. It should not be the same as the group_id.

When a plugin version has been created, its status is set to DRAFT. As described in Version lifecycle, A DRAFT plugin version can still be edited and is not available to customers.

Via API

To create a plugin using the API, send a POST request to:

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

Body

Name	Type
plugin_type	string
organisation_id	string
group_id	string
artifact_id	string

Response

200

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

Create a version

Via UI

After creating a plugin, you can add a new version.

1. Click on New Version

2. Configure your new version:

Parameters	Description
Version	Must follow the expected format: 1.0.0, 1.2.0, 1.2.0-rcl. The version can include three digits and an optional suffix.
Engine type	Specifies the system where the plugin will be executed.
Plugin properties	Define the context in which the plugin will be used. These properties are sent to your plugin. provider (mandatory): Name of the plugin version creator. name (mandatory): Version name

For AUDIENCE_SEGMENT_EXTERNAL_FEED, a specific parameter "Use file delivery" must be set to indicate whether the feed uses the file delivery service. This field is optional and defaults to false.

By API

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

Path Parameters

Name	Type	Description
plugin_id	integer	The ID of your plugin

Request Body

Name	Type
plugin_properties	array
version_id	string
maintainerId (optinal)	string
file_delivery_activated (optinal)	boolean (false by default)

200

{   
    "status": "ok",
    "data": {
      "version_id":"1.0.0",
      "plugin_properties":[{
            "technical_name": "provider",
            "value": {
                "value": "mediarithmics"
                },
            "property_type": "STRING",
            "origin": "PLUGIN_STATIC",
            "writable": false,
            "deletable": false
            },
            {
            "technical_name": "name",
            "value": {
                "value": ""
                },
            "property_type": "STRING",
            "origin": "PLUGIN_STATIC",
            "writable": false,
            "deletable": false
            }
    ]}
}

Additional Notes:

When defining the properties required for your code to run, you can reuse properties from your test files. However, be sure to remove any default values before finalizing the configuration.

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"
}

Add configuration file(s)

A configuration file is used to store credentials, connection parameters, or other technical settings required for a specific customer, organization or datamart. It typically contains environment-specific values such as API keys, authentication tokens, or endpoint URLs that allow the plugin to function correctly within a given deployment. These files ensure that configurations remain flexible and adaptable without modifying the core plugin code.

Via UI

All configuration files are displayed in the Technical Configuration section of the plugin version.

To add a new configuration file:

1. Click on the Technical Configuration menu.

2. Click Add a Technical Configuration.

3. Enter a name for the configuration file.

4. Define the content in JSON format.

To update an existing configuration file:

1. Click Edit in the menu of the configuration file list.

2. Modify the JSON content as needed.

3. Click Save to apply the changes.

Via API

To upload or update a configuration file using the API, send a PUT request to:

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

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

Add 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.

Via API

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

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

Meanwile, please add a look to Coding your plugin section to learn more about this.

Deploy your build

Via UI

Once your configuration is complete and your build is set up, you can deploy your version on the Mediarithmics platform.

1. Navigate to the Overview tab of your version.

2. Click Deploy the version.

3. If your version's engine type is HOSTED_CONTAINERS, enter your build tag.

4. For HOSTED_CONTAINERS, the version status will be set to DEPLOYING while the containers are being created.

5. Once deployment is complete, the version status changes to TESTING.

Via API

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

For HOSTED_CONTAINERS plugins, you must verify whether your version has been deployed in running containers. If no containers are running, the version will not be usable.

Via UI

In the Computing console, after selecting your plugin and its version, you can access the Deployment tab to view key details about your deployment, including the name and number of running containers.

Additionally, you can update your containers by applying a new build tag, allowing you to modify the code without creating a new version. However, this approach should be used only for minor updates, such as debugging your existing version.

Via API

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
}