Perion
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
LeadandSignup, which are not included in the default MetaRouter integration. These must be mapped manually. - The MetaRouter sync session ID is mapped to the
session_idfield 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_utidis required for user-level attribution and must be included in server-side events. - A
perion_sessionIDcan 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_utidandperion_sessionIDare 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 Parameter | Description |
|---|---|
ADVERTISER_ID | Unique 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 Key | Description | Expected Input |
|---|---|---|
advertiser_idRequired | String: Advertiser account ID provided by Perion. | Enrichment – staticString: $$ADVERTISER_ID$$ |
partner_idRequired | Integer: Partner ID assigned by Perion for integration tracking. | Enrichment – staticInt: 65 |
user.idRequired | String: Perion user identifier used for attribution and identity resolution. | context.providers.perion.utid |
user.client_ipRequired | String: IP address of the user for geolocation and tracking. | context.ip |
user.uaRequired | String: User agent string used to identify browser/device. | context.userAgent |
session_id | String: Identifier used to group user activity into a single session. | context.providers.perion.sessionID |
category | String: Page category or section, typically derived from the page title. | context.page.title |
sub_category | String: Sub-category of the page, usually the URL path. | context.page.path |
referral_url | String: Full URL of the referring page. | context.page.referrer |
referral_source | String: Categorized source of referral (e.g. direct, tiktok, facebook). | Expression – parses context.page.referrer to detect sources |
Event Specific
Product Viewed
| Output Key | Description | Expected Input |
|---|---|---|
| Tracker ID Required | Array: Static tracker ID assigned by Perion for this event type. | Expression – return { tracker_ids = { ex.00000 } } |
products | Array 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 Key | Description | Expected Input |
|---|---|---|
| Tracker ID Required | Array: Static tracker ID assigned by Perion for this event type. | Expression – return { tracker_ids = { ex.00000 } } |
currency | String: Currency code for the cart total. | properties.currency |
transaction_id | String: Unique identifier for the cart transaction. | properties.cart_id |
transaction_total | Double: Total value of the cart including all items. | Expression – calculates sum of price * quantity for all products |
shipping_cost | Double: Cost of shipping the cart items. | properties.shipping |
products | Array 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 Key | Description | Expected Input |
|---|---|---|
| Tracker ID Required | Array: Static tracker ID assigned by Perion for this event type. | Expression – return { tracker_ids = { ex.00000 } } |
currency | String: Currency code for the transaction. | properties.currency |
transaction_id | String: Unique identifier for the completed order. | properties.order_id |
transaction_total | Double: Final total of the transaction including discounts and shipping. | properties.total |
coupon_code_used | String: Coupon or discount code used in the order. | properties.coupon |
shipping_cost | Double: Shipping cost applied to the order. | properties.shipping |
products | Array 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.
| Attribute | Example | Sync Injector Required? |
|---|---|---|
user.id Required | a1b2c3d4e5_perion_utid | Yes |
user.client_ip Required | 192.0.2.1 | No |
user.ua Required | Mozilla/5.0 (Macintosh...) | No |
session_id Recommended | 1746702483972 | Yes (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.
Updated 2 months ago