📘

This integration is currently in beta. Contact your MetaRouter support team to get started.

What Is Perion?

Perion connects advertisers with consumers through technology across all major digital channels. Its cross-channel creative and technological strategies enable brands to maintain a powerful presence across the entire consumer journey, online and offline. Perion is dedicated to building an advertiser-centric universe, providing significant benefits to brands and publishers.


Website: https://perion.com/

Product Type: Advertising

Integration Type: Starter Kit & ID Sync

Event Source Type: Web

Event Scope: Conversion & Non-conversion Events


Capabilities

  • Tracks key events like product views, cart views, and purchases.
  • ID sync captures the Perion ID (perion_utid) and supports optional session ID generation.
  • Sends event data server-to-server without needing a browser tag.
  • Includes product details like UPC, SKU, name, category, quantity, and price.
  • Captures referral URL, session ID, and referral source for attribution.
  • Includes IP address and user agent to support user tracking and geolocation.

Considerations

  • Perion must provide a unique tracker ID for each event. Coordinate directly with your Perion representative to align on the events you plan to track.
  • Perion supports non-standard AJS events such as Lead and Signup, which are not included in the default MetaRouter integration. These must be mapped manually.
  • The MetaRouter sync session ID is mapped to the session_id field by default. This can be overridden with your own session identifier if needed.

Identity Sync

  • Sync Available: Yes
  • Required for Starter Kit: Yes
  • Prerequisites: To enable this sync, you must contact Perion and request that your domain be added to their list of allowed CORS origins.
  • Documentation: Perion Sync

Sync Details

  • The Perion sync captures the Perion user ID (perion_utid) through a first-party identity request.
  • The perion_utid is required for user-level attribution and must be included in server-side events.
  • A perion_sessionID can be automatically generated by MetaRouter if the “Use Session Sync” setting is enabled, or you can provide your own.
  • If you provide your own session ID, you must update the starter kit mapping to reflect your custom value.
  • Both perion_utid and perion_sessionID are stored as first-party cookies with configurable lifetimes.
  • The sync requires Perion to add your domain to their CORS allowlist to enable identity resolution.

Starter Kit Setup Guide

1. Deploy the Perion Sync

  • To collect the sync values (e.g., perion_utid, perion_sessionID), you must implement a Perion ID sync. Refer to the following documentation to complete the setup: Perion – ID Sync Guide.

2. Gather Credentials

To begin setup, contact your Perion representative to obtain the following:

  • Advertiser ID
  • Tracker IDs for each event you plan to send (e.g., product views, cart views, purchases)

3. Add a Perion Integration

From the integration library, add a Perion integration. Then, fill out the Connection Parameters:

Connection ParameterDescription
ADVERTISER_IDUnique ID provided by Perion to identify your advertiser account. Required for all event tracking.

3. Configure Event Mapping

  • MetaRouter provides all event mappings typically required for Perion integrations, aligned with standard AJS specifications. You may add custom events, parameters or mappings in accordance with Perion’s API documentation. Please see below for details on event mapping.

4. Deploy to Pipeline

  • In the Pipelines tab, add your Perion integration.
  • Select the correct integration revision
  • Click Add Integration to finalize deployment.

Event Mappings

Global

Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.

Output KeyDescriptionExpected Input
advertiser_id
Required
String: Advertiser account ID provided by Perion.Enrichment – staticString: $$ADVERTISER_ID$$
partner_id
Required
Integer: Partner ID assigned by Perion for integration tracking.Enrichment – staticInt: 65
user.id
Required
String: Perion user identifier used for attribution and identity resolution.context.providers.perion.utid
user.client_ip
Required
String: IP address of the user for geolocation and tracking.context.ip
user.ua
Required
String: User agent string used to identify browser/device.context.userAgent
session_idString: Identifier used to group user activity into a single session.context.providers.perion.sessionID
categoryString: Page category or section, typically derived from the page title.context.page.title
sub_categoryString: Sub-category of the page, usually the URL path.context.page.path
referral_urlString: Full URL of the referring page.context.page.referrer
referral_sourceString: Categorized source of referral (e.g. direct, tiktok, facebook).Expression – parses context.page.referrer to detect sources

Event Specific

Product Viewed

Output KeyDescriptionExpected Input
Tracker ID
Required
Array: Static tracker ID assigned by Perion for this event type.Expression – return { tracker_ids = { ex.00000 } }
productsArray of Objects: Product viewed, includes basic product metadata.Expression – sends upc_id, sku_id, product_name, product_category, quantity, and price.

Perion also accepts product_description, which is not included in the standard integration.

Cart Viewed

Output KeyDescriptionExpected Input
Tracker ID
Required
Array: Static tracker ID assigned by Perion for this event type.Expression – return { tracker_ids = { ex.00000 } }
currencyString: Currency code for the cart total.properties.currency
transaction_idString: Unique identifier for the cart transaction.properties.cart_id
transaction_totalDouble: Total value of the cart including all items.Expression – calculates sum of price * quantity for all products
shipping_costDouble: Cost of shipping the cart items.properties.shipping
productsArray of Objects: List of cart items with product details.Expression – sends upc_id, sku_id, product_name, product_category, quantity, and price.

Perion also accepts product_description, which is not included in the standard integration.

Order Completed

Output KeyDescriptionExpected Input
Tracker ID
Required
Array: Static tracker ID assigned by Perion for this event type.Expression – return { tracker_ids = { ex.00000 } }
currencyString: Currency code for the transaction.properties.currency
transaction_idString: Unique identifier for the completed order.properties.order_id
transaction_totalDouble: Final total of the transaction including discounts and shipping.properties.total
coupon_code_usedString: Coupon or discount code used in the order.properties.coupon
shipping_costDouble: Shipping cost applied to the order.properties.shipping
productsArray of Objects: Purchased items with full product data.Expression – sends upc_id, sku_id, product_name, product_category, quantity, and price.

Perion also accepts product_description, which is not included in the standard integration.

Note: Perion also supports additional event types such as Lead and Signup. To enable these, contact your Perion representative to obtain the appropriate tracker IDs. You may also contact your MetaRouter Customer Success representative if assistance is needed to custom map these events.


Required & Recommended Identifiers

These identifiers must be mapped to Perion in order for successful user matching to occur. Without these IDs, any events sent to Perion may not be accurately reflected in reporting. For your convenience, required and recommended IDs are mapped as Global parameters to ensure they are added to every event.

AttributeExampleSync Injector Required?
user.id Requireda1b2c3d4e5_perion_utidYes
user.client_ip Required192.0.2.1No
user.ua RequiredMozilla/5.0 (Macintosh...)No
session_id Recommended1746702483972Yes (if using MetaRouter-generated session sync)

Integration Validation

Work directly with your Perion representative to validate that event and user data are being received and attributed correctly on their backend. Confirm whether they prefer to test in a sandbox or staging environment, and coordinate test events accordingly. Additionally, ensure you align with your Perion contact on a tag-to-server-side transition plan to prevent any data loss or duplication during the switchover.