Developer
User guidesDeveloper websiteHelp centerLog in
  • Welcome!
  • Organisations structure
    • Datamart
    • Users and roles
  • User points
    • User identifiers
      • Networks IDs
        • Device-based Network IDs
          • Custom Device ID integration
          • ID5
          • First ID
        • User-based Network IDs
          • Custom User ID integration
          • UTIQ martechpass
      • Accounts
      • Emails
      • Device identifiers
    • User activities and events
    • Compartments
    • User profiles
    • User segments
    • Hyper point & Quarantine
  • Data model
    • Defining your schema
    • Computed fields
      • Concepts
      • Setup
      • Development
      • Examples
  • Data ingestion
    • Real time user tracking
      • Website tracking
      • Mobile apps tracking
      • Ads exposure tracking
      • AMP tracking
      • Conversions tracking
      • Email views and clicks
      • Tracking API
      • Event rules
      • Activity analyzers
    • Bulk processing
      • Imports
        • User activities import
        • User profiles import
        • User choices import
        • Segments import
      • Deletions
        • User identifiers deletion
        • Device points deletion
        • User points deletion
      • User identifiers association
      • Integration batch
    • Activities analytics
    • Data warehouse
      • Preliminary setup
        • BigQuery
      • Create data warehouse
  • Querying your data
    • OTQL queries
    • OTQL examples
    • GraphQL queries
    • UserPoint API
    • User activities
    • Activities analytics queries
      • API Quickstart
      • Dimensions and metrics
      • Use cases
    • Funnel API
  • Alerting
    • Alert configurations
  • Data visualisation
    • Quickstart
    • Dashboards
    • Sections and cards
    • Charts
    • Datasets and data sources
      • Using a data file data source
    • Transformations
    • Filters
    • Cookbook
    • Reference
  • Advanced usages
    • Audience segmentation
      • Audience features
      • Segment builders
      • Audience segment metrics
      • Audience segment feed
        • Building new feeds
        • Monitoring a feed
        • Curated Audiences (SDA)
      • Edge segments
      • Cohort-based Lookalike
    • Contextual targeting
      • Setup
      • Activation
        • Google Ad Manager
        • Xandr (through prebid.js)
      • API documentation
    • Exporting your data
      • Query Exports
      • Datamart replication
    • Data privacy compliance
      • User choices
      • Cleaning rules
      • Exercise of user rights
      • Cookies
    • Campaigns
    • Automations
      • Email routers
      • Email renderers
      • Opt-in provider
      • Custom action plugins
      • Usage limits for automations
    • Plugins
      • Concepts
      • Creation & Deployment
      • Coding your plugin
      • Manage existing plugins
      • Layouts
      • Presets
      • Monitoring
      • Throttling
      • Batching (for external feeds)
    • Platform monitoring
      • Resources usage
        • Dimensions and metrics
      • Collection volumes
        • Dimensions and metrics
      • Events ingestion monitoring
        • Dimensions and metrics
    • Data Clean Room
      • Bunker
      • Clean room
  • Resources
    • Tutorial: Data Ingestion
      • Your first events
        • Add the mediarithmics tag
          • Getting the tag
          • Adding the tag
        • Send events using the tag
          • Adding event properties
          • Finding the UserEvent type in your schema
          • Matching your schema
          • Standard events
      • Your first bulk imports
        • API basics
          • Authentication
          • Your first API call
        • Send documents using the API
          • Requirements
          • Sending documents
    • Using our API
      • Authentication
    • Tools & libraries
      • mics CLI
      • JS Tag
      • Plugin SDK
    • Data cubes
      • Creating a report
      • Reference
Powered by GitBook
On this page
  • Layout JSON file
  • Example
  • Schema
  • Translation files
  • Managing layouts
  • Get a layout
  • Upload a layout
  • Get a translation file
  • Upload a translation file

Was this helpful?

Export as PDF
  1. Advanced usages
  2. Plugins

Layouts

PreviousManage existing pluginsNextPresets

Last updated 3 months ago

Was this helpful?

As a plugin developer, you customize the new/edit plugin instance screens with a layout JSON file. You can group properties into categories and choose the type of field representing each of them.

A plugin layout is bound to a .

It is optional, except for . A default layout is used to show all properties of a plugin version (Note that there is no layout file associated with this default layout).

A plugin layout is composed of:

  1. A layout JSON file

  2. A non-empty list of translation CSV files

Layout JSON file

This file declares the different elements of the configuration UI.

Example

{
	"version": "V202005",
	"sections": [
		{
			"title": "{{section_title}}",
			"sub_title": "{{section_subtitle}}",
			"fields": [
				{
					"property_technical_name": "property_1",
					"field_type": "INPUT",
					"label": "{{property_1_label}}",
					"tooltip": "{{property_1_tooltip}}",
					"required": true
				},
				{
					"property_technical_name": "property_2",
					"field_type": "MULTI_SELECT",
					"label": "{{property_2_label}}",
					"tooltip": "{{property_2_tooltip}}",
					"enum": [
						{
							"value": "COOKIE",
							"label": "{{COOKIE_label}}"
						},
						{
							"value": "CUSTOMER",
							"label": "{{CUSTOMER_label}}"
						},
						{
							"value": "IDFA",
							"label": "{{IDFA_label}}"
						},
						{
							"value": "AD_ID",
							"label": "{{AD_ID_label}}"
						}
					],
					"required": true
				}
			],
			"advanced_fields": [
				{
					"property_technical_name": "segment_name",
					"field_type": "INPUT",
					"label": "{{segment_name_label}}",
					"tooltip": "{{segment_name_tooltip}}",
					"required": false
				},
				{
					"property_technical_name": "segment_description",
					"field_type": "INPUT",
					"label": "{{segment_description_label}}",
					"tooltip": "{{segment_description_tooltip}}",
					"required": false
				},
				{
					"property_technical_name": "customer_user_identifier",
					"field_type": "INPUT",
					"label": "{{customer_user_identifier_label}}",
					"tooltip": "{{customer_user_identifier_tooltip}}",
					"required": false
				},
				{
					"property_technical_name": "continent",
					"field_type": "SELECT",
					"label": "{{continent_label}}",
					"tooltip": "{{continent_tooltip}}",
					"enum": [
						{
							"value": "NAM",
							"label": "NAM"
						},
						{
							"value": "EMEA",
							"label": "EMEA"
						},
						{
							"value": "APAC",
							"label": "APAC"
						}
					],
					"required": false
				}
			]
		}
	],
	"metadata": {
		"large_icon_asset_id": "13636",
		"small_icon_asset_id": "13636",
		"display_name": "{{section_title}",
		"description": "{{section_subtitle}}"
	}
}

Schema

Here is the JSON schema. You can validate your files with it in your favorite JSON validation tool.

{
    "$schema": "http://json-schema.org/schema#",
    "definitions": {
    "PluginLayoutMetadataResource": {
    "type": "object",
      "properties": {
        "large_icon_asset_id": {"type": "string"},
        "small_icon_asset_id": {"type": "string"},
        "large_icon_asset_url": {"type": ["string", "null"]},
        "small_icon_asset_url": {"type": ["string", "null"]},
        "tooltip": {"type": ["string", "null"]},
        "display_name": {"type": "string"},
        "description": {"type": "string"}
      },
      "required": ["large_icon_asset_id", "small_icon_asset_id", "display_name", "description"]
    },
    "PluginLayoutEnumResource": {
      "type": "object",
      "properties": {
        "value": {"type": "string"},
        "label": {"type": "string"}
      },
      "required": ["value", "label"]
    },
    "PluginLayoutFieldResource": {
      "type": "object",
      "properties": {
        "property_technical_name": {"type": "string"},
        "field_type": {"type": "string"},
        "label": {"type": "string"},
        "tooltip": {"type": ["string", "null"]},
        "enum": {"type": ["array", "null"],
          "items": {
            "$ref": "#/definitions/PluginLayoutEnumResource"
          }
        },
        "max_length": {"type": ["integer", "null"]},
        "required": {"type": ["boolean", "null"]}
      },
      "required": ["property_technical_name", "field_type", "label"]
    },
    "PluginLayoutSectionResource": {
      "type": "object",
      "properties": {
        "title": {"type": "string"},
        "sub_title": {"type": "string"},
        "fields": {"type": "array",
          "items": {
            "$ref": "#/definitions/PluginLayoutFieldResource"
          }
        },
        "advanced_fields": {"type": "array",
          "items": {
            "$ref": "#/definitions/PluginLayoutFieldResource"
          }
        }
      },
      "required": ["title", "sub_title", "fields", "advanced_fields"]
    }
  },

  "type": "object",
  "properties": {
    "version": {"type": "string"},
    "sections": {"type": "array",
      "items": {
        "$ref": "#/definitions/PluginLayoutSectionResource"
      }
    },
    "metadata": {"$ref": "#/definitions/PluginLayoutMetadataResource"}
  },
  "required": ["version", "sections", "metadata"]
}

Root

Attribute

Type

Description

version

a string

the version of the layout

sections

metadata

Sections

Attribute

Type

Description

title

a string

the section title

sub_title

a string

the section subtitle

fields

advanced_fields

Fields

Attribute

Type

Description

property_technical_name

a string

the technical name of the property represented by the field

field_type

a field type string enum

label

a string

the label preceding the field type, on its left in the form

tooltip

a string (optional)

the help text displayed in the tooltip following the field type, on its right in the form

enum

max_length

an integer (optional)

a maximum length of the text in the field type; used only in the case TEXTAREA

required

a boolean (optional)

it defines whether the field is mandatory or not; if the value is not specified, then it isn't (the default value is false)

The possible field types are the following:

  • TEXTAREA

  • URL

  • DATA_FILE

  • HTML

  • NUMBER

  • SELECT

  • MULTI_SELECT

  • IMAGE

  • INPUT

  • INPUT_NUMBER

  • SWITCH

  • RADIO

  • CHECKBOX

  • DATE

  • DATE_RANGE

Enum

Attribute

Type

Description

value

a string

the value of the enum, which will be affected to the property

label

a string

the label of the enum, which will be displayed in the field

Metadata

Attribute

Type

Description

large_icon_asset_id

an integer

the asset id of the large icon representing the plugin layout

small_icon_asset_id

an integer

the asset id of the small icon representing the plugin layout

display_name

a string

the plugin version's name (visible in the plugin listing and the form page)

description

a string

a description of the plugin version (visible in the plugin listing and the form page)

Note that the assets must belong to the same organisation than the plugin.

Translation files

Translation csv files are used to support localization. Given a layout json file, for each locale, a translation csv file can be provided. The plugin developer can refer to a value in the layout json file by surrounding the value name with double curly brackets (hence, referring to value val is done with {{val}} in the json file). Those values can be found anywhere in the layout json file. For example, an excerpt of a layout json file, referring to the value val when defining a label in a field, looks like:

{
  "property_technical_name":"name",
  "field_type":"TEXTAREA",
  "label":"{{val}}"
}

A translation csv is composed of two comma-separated columns. The header of the table is KEY,VALUE. The first column corresponds to the keys, i.e the names of the values (val in the preceding example). The second column corresponds to the values by which the keys will be replaced when the layout is displayed in Navigator. Considering the previous excerpt of a layout json file, a (brief) corresponding US English (en-US locale) translation csv file could be:

KEY,VALUE
val,"Hello World!"

Here is a sample translation file associated with the sample layout.json file in this page

KEY,VALUE
section_title,"Beeswax Audience Feed"
section_subtitle,"Synchronize audiences with Beeswax"
buzz_key_label,"Buzz key"
buzz_key_tooltip,"Your buzz key as provided by Beeswax. Warning : valid credentials should be set into mediarithmics for this buzz key. If an authentication error is displayed when saving, contact your account manager."
identifiers_to_send_label,"Types of user identifiers sent"
identifiers_to_send_tooltip,""
BEESWAX_label,"Cookie ids"
CUSTOMER_label,"Customer ids"
IDFA_label,"IOS ids"
AD_ID_label,"Android ids"
segment_name_label,"Segment name"
segment_name_tooltip,"The name of the segment that will be populated in Beeswax. Default to mediarithmics segment name."
segment_description_label,"Segment description"
segment_description_tooltip,"The description of the segment that will be populated in Beeswax. Default to mediarithmics segment description."
advertiser_id_label,"Advertiser ID",
advertiser_id_tooltip,"If segment should not belong to the overall beeswax account but to a specific advertiser, please enter its ID.",
customer_user_identifier_label,"Customer identifier"
customer_user_identifier_tooltip,"Path to the customer identifier property when sending customer ids. Examples : USER_EMAIL:hash | USER_AGENT:mappings[0].user_agent_id"
continent_label,"Continent"
continent_tooltip,"The destination continent data centers to upload the data. Only one continent may be specified per upload."

Managing layouts

Get a layout

In the computing console, choose your plugin, select a plugin version, and open the section Layout in the menu. You should get at least two files in the list, the properties layout and the en-US translation. Click on the file options and select Edit to display the content.

If you don't have those files, you can create them by clicking on Add a properties layout and Add a local to create a translation.

You can also use our API to manage your layouts:

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

Retrieves the already uploaded layout JSON file for a plugin version. You can retrieve the layout.json file with translation tokens or with translation values.

Path Parameters

Name
Type
Description

plugin_id

integer

The ID of the plugin

version_id

integer

The ID of the version

Query Parameters

Name
Type
Description

locale

string

Replaces all translation tokens with values in the specified locale Example: locale=en-US

Upload a layout

PUT https://api.mediarithmics.com/v1/plugins/:pluginId/versions/:versionId/properties_layout

Updates the layout JSON file for a plugin version

Path Parameters

Name
Type
Description

plugin_id

integer

The ID of the plugin

version_id

integer

The ID of the version

Request Body

Name
Type
Description

body

string

The layout.json file content

Get a translation file

GET https://api.mediarithmics.com/v1/plugins/:pluginId/versions/:versionId/properties_layout/localizations/locale=:locale

Retrieves the translation file of a plugin version in the specified locale

Path Parameters

Name
Type
Description

locale

string

The locale in which to retrieve the CSV file.

plugin_id

integer

The ID of the plugin.

version_id

string

The ID of the version.

Upload a translation file

PUT https://api.mediarithmics.com/v1/plugins/:pluginId/versions/:versionId/properties_layout/localizations/locale=en-US

Retrieves the translation file of a plugin version in the specified locale

Path Parameters

Name
Type
Description

locale

string

The locale in which to retrieve the CSV file.

plugin_id

integer

The ID of the plugin

version_id

integer

The ID of the version

Request Body

Name
Type
Description

body

string

The content of the file

a list of

it defines the form's sections (see below for the )

a resource

it defines metadata concerning the form (see below for the )

a list of

it defines the fields of the section (see below for the )

a list of

it defines the advanced fields of the section, which can be graphically expanded or not (see below for the )

the type of the input form field (see below for the )

a list of resources (optional)

an enum describing the possible values of the field (used by some field types : SELECT, MULTI_SELECT, SWITCH, RADIO, CHECKBOX) (see below for the )

In case of JSON not structured as expected error, you can use to validate your file.

Schema
Definition
Definition
Definition
Definition
Definition
Definition
Sections
Metadata
Fields
Fields
Enum
audience segment feeds
plugin version