# Creation & Deployment

## Summary

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

1. [Create a plugin](#create-a-plugin) 
2. [Create a version](#create-a-version)
3. [Add configuration file(s)](#add-configuration-file-s)
4. [Add external services](#add-external-services)
5. [Deploy your code](#deploy-your-code)
6. [Deploy you build](#deploy-your-build)
7. [Check deployment status](#check-deployment-status)

## Create a plugin

### **Via UI**

To create a new plugin:

1. Click **New Plugin**.
2. Configure the following parameters:

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

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:

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/plugins`

**Body**

| Name              | Type   |
| ----------------- | ------ |
| `plugin_type`     | string |
| `organisation_id` | string |
| `group_id`        | string |
| `artifact_id`     | string |

**Response**

{% tabs %}
{% tab title="200 " %}

```json
{
  "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
  }
}
```

{% endtab %}
{% endtabs %}

## 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:&#x20;

<table><thead><tr><th width="214">Parameters</th><th>Description</th></tr></thead><tbody><tr><td>Version</td><td>Must follow the expected format: <code>1.0.0</code>, <code>1.2.0</code>, <code>1.2.0-rcl</code>. The version can include three digits and an optional suffix.</td></tr><tr><td>Engine type</td><td>Specifies the system where the plugin will be executed.</td></tr><tr><td>Plugin properties</td><td><p>Define the context in which the plugin will be used. These properties are sent to your plugin.</p><ul><li><strong>provider</strong> (mandatory): Name of the plugin version creator.</li><li><strong>name</strong> (mandatory): Version name</li></ul></td></tr></tbody></table>

{% hint style="warning" %}
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**.
{% endhint %}

### By API

<mark style="color:green;">`POST`</mark> `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) |

{% tabs %}
{% tab title="200 " %}

```json
{   
    "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
            }
    ]}
}
```

{% endtab %}
{% endtabs %}

**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:

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

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

{% hint style="info" %}
**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.
{% endhint %}

#### `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:

<mark style="color:orange;">`PUT`</mark> `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

<mark style="color:green;">`POST`</mark> `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`                                                                             |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
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.
{% endhint %}

## Deploy your code

{% hint style="info" %}
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](https://developer.mediarithmics.io/advanced-usages/plugins/creation) section to learn more about this.
{% endhint %}

## 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

<mark style="color:green;">`POST`</mark> `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 | <p><code>DEPLOY\_PLUGIN</code> for new versions<br><code>UPGRADE\_ALL\_CONTAINERS</code> to update the code of an existing version</p> |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The deployment can take from 5 to 10 minutes.
{% endhint %}

## 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

<mark style="color:blue;">`GET`</mark> `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 |

{% tabs %}
{% tab title="200 " %}

```json
{
    "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
}
```

{% endtab %}
{% endtabs %}