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
  • Endpoints to implement
  • Trigger a custom action
  • Available outbound services
  • Retrieve the instance
  • Retrieve the instance properties
  • Creating a custom action plugin
  • Interfaces to implement
  • Create a custom action plugin instance
  • Update a custom action plugin instance property
  • Debugging
  • Plugin logs and metrics

Was this helpful?

Export as PDF
  1. Advanced usages
  2. Automations

Custom action plugins

PreviousOpt-in providerNextUsage limits for automations

Last updated 4 years ago

Was this helpful?

A custom action plugin is a that can be associated to a custom action node in an automation, allowing you to trigger a custom action in an automation.

This feature is useful for triggering actions not available in the current list of actions in automations.

If you don't know what a plugin is, you can find

Endpoints to implement

Custom action plugins have only one predefined endpoint to implement.

Trigger a custom action

POST myworker/v1/scenario_custom_actions

This entry point is called any time a user point goes through a custom action node in an automation.

Request Body

Name
Type
Description

user_point_id

string

The ID of the user point.

custom_action_id

string

The ID of the custom action plugin instance. Used to retrieve the instance properties.

{
    "status": "ok"
}
{
  "status": "error",
  "message": "..."
}

See to learn why you should use the custom_action_id parameter to retrieve the instance properties.

Available outbound services

Retrieve the instance

GET https://api.mediarithmics.com/v1/scenario_custom_actions/:id

Use the custom_action_id from the incoming request to retrieve the custom action plugin instance that has been called.

Path Parameters

Name
Type
Description

id

string

ID of the custom action plugin instance, typically the custom_action_id from the incoming request.

{
  "status": "ok",
  "data": {
    "id": "1000",
    "name": "Custom action plugin example",
    "organisation_id": "1000",
    "group_id": "com.example-organisation.scenario-custom-action",
    "artifact_id": "example-organisation-example-custom-action"
    "creation_ts": 1617100419508,
    "created_by": "28453014",
    "version_id": "1001",
    "version_value": "1.0.0"
  }
}

Retrieve the instance properties

GET https://api.mediarithmics.com/v1/scenario_custom_actions/:id/properties

Get the properties associated with the custom action plugin instance.

Path Parameters

Name
Type
Description

id

string

ID of the custom action plugin instance, typically thecustom_action_id from the incoming request

{
  "status": "ok",
  "data": [
    {
      "technical_name": "provider",
      "value": { "value": "mediarithmics" },
      "property_type": "STRING",
      "origin": "PLUGIN_STATIC",
      "writable": true,
      "deletable": false
    },
    {
      "technical_name": "name",
      "value": { "value": "Custom action example" },
      "property_type": "STRING",
      "origin": "PLUGIN_STATIC",
      "writable": false,
      "deletable": false
    }
  ]
}

Creating a custom action plugin

A custom action plugin has the SCENARIO_CUSTOM_ACTION plugin type. Its group id should be {domain.organisation.scenario-custom-action} (for example com.mediarithmics.scenario-custom-action).

Its artifact id should be the name of the custom action plugin, i.e. example-custom-action.

We can provide you with a Hello World project using our SDK. Please contact your support to gain access to it.

Interfaces to implement

You should extend CustomActionBasePlugin class and implement the onCustomActionCall function from the plugin SDK.

The onCustomActionCall function is called every time a user point runs through a custom action node in an automation. It is responsible for implementing the custom action.

Don't forget to catch your errors. You should log / respond with the appropriate message to facilitate debugging.

import { core } from '@mediarithmics/plugins-nodejs-sdk';

export class MyCustomActionPlugin extends core.CustomActionBasePlugin {
  protected onCustomActionCall(
    request: core.CustomActionRequest,
    instanceContext: core.CustomActionBaseInstanceContext
  ): Promise<core.CustomActionPluginResponse> {

    // do stuff here

    const response: core.CustomActionPluginResponse = {
      status: 'ok',
    };

    return Promise.resolve(response);
  }
}

Create a custom action plugin instance

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

Use this method to create a custom action plugin instance attached to an organisation. This will display the custom action as a choice in the custom action automation node.

Request Body

Name
Type
Description

organisation_id

string

The ID of the organisation you want to attach this instance to.

name

string

The name for this instance. If not given, the instance ID will be used in the interface instead.

artifact_id

string

The artifact ID of the plugin.

group_id

string

The group ID of the plugin.

{
    "status": "ok",
    "data": {
        "id": "string",
        "name": "string",
        "organisation_id": "string",
        "group_id": "string",
        "artifact_id": "string",
        "creation_ts": 1618842498220,
        "created_by": "string",
        "version_id": "string",
        "version_value": "string"
    }
}

Update a custom action plugin instance property

PUT https://api.mediarithmics.com/v1/scenario_custom_actions/:id/properties/technical_name=:name

Use this method to update a property for the custom action plugin instance.

Path Parameters

Name
Type
Description

name

string

The technical name of the property to update.

id

string

The ID for the custom action plugin instance.

Request Body

Name
Type
Description

deletable

boolean

writable

boolean

origin

string

One of PLUGIN_STATIC, PLUGIN, INSTANCE.

property_type

string

One of DOUBLE, INT, BOOLEAN, ASSET, DATA_FILE, URL, STRING, AD_LAYOUT, STYLE_SHEET, PIXEL_TAG, RECOMMENDER, NATIVE_IMAGE, NATIVE_TITLE, NATIVE_DATA.

technical_name

string

The technical name of the property to update.

value

object

Value format depends on property type. If property type is STRING, value will be an object {"value": "string"}.

{
    "status": "ok",
    "data": {
        "technical_name": "string",
        "value": {
            "value": "string"
        },
        "property_type": "STRING",
        "origin": "PLUGIN",
        "writable": true,
        "deletable": false
    }
}

Debugging

Plugin logs and metrics

The code of the custom action plugin can call the following API endpoints to retrieve.

See the documentation to see .

Use our to create your custom action plugin in Node.js: the required routes are already defined and you only have to override specific functions.

You can find a sample custom action plugin .

The project structure and files work as .

You can monitor custom action plugins.

plugins
how plugins are created and deployed
Plugin SDK
in the examples folder of the plugin SDK
with every other plugin
as you do with all plugins
plugin
complete documentation in the specific section.
Plugin Instances
its instance context