📘

Right now, this service needs to be initially set up and configured by the MetaRouter team within your cluster.

Overview

The Enrichment Service allows you to securely call an external API—such as a customer database, loyalty API, or geo service—to retrieve additional information about a user based on identifiers available in your website’s data layer.

Values retrieved through the Enrichment Service are securely returned to the browser and stored locally. These values can then be attached to events and forwarded to downstream analytics or activation platforms.

This enables organizations to enrich their event streams with additional user context at the moment events are produced, without exposing sensitive credentials or requiring direct browser access to protected APIs.

Common Use Cases

Some scenarios that may require the Enrichment Service include:

• Matching a user’s login ID to an email address for downstream audience activation.
• Querying a loyalty API to retrieve attributes such as membership tier or reward status.
• Matching a user’s IP address against a geo database to enable geographic reporting.
• Looking up user attributes from an internal customer database to support analytics.

---

How It Works

The Enrichment Service works in conjunction with your MetaRouter cluster and the Sync Injector library installed on your website.

1. The Sync Injector makes an API call from the browser to your MetaRouter cluster.
2. The cluster securely proxies the request to the configured external API, resolving any stored credentials required to access the API.
3. The external API returns the requested data to the cluster.
4. The cluster encrypts the response data and returns it to the browser.
5. The browser stores the encrypted values locally.
6. When events are sent, the enriched values are attached to the event payload.
7. When events are forwarded to vendors, MetaRouter decrypts the values for integrations that have been granted access.

This architecture ensures sensitive information is never exposed in the browser while still enabling client-side enrichment.

---

Key Benefits

Real-Time Data Enrichment

Enrich events with additional context as they are generated, enabling faster analytics insights and activation workflows.

Secure API Access

The Enrichment Service securely handles sensitive data and credentials:

• API credentials are stored server-side within MetaRouter.
• Header tokens and OAuth2 authentication are supported.
• Sensitive data is encrypted before being returned to the browser.

Reduced API Load

Retrieved values are stored in the browser, limiting the number of requests made to your API.

Privacy and Compliance

Encrypted values ensure sensitive user information is never directly exposed within the browser environment.

---

Prerequisites

Before configuring the Enrichment Service, ensure the following:

• The Sync Injector is deployed on your website.
• You have access to a performant API endpoint that can respond quickly to enrichment requests.
• An identifier exists in your data layer that can be used to perform lookups (for example: userId, loginId, or ip).

---

Customer Setup Guide

Step 1 — Identify Required Data

Provide the following information to MetaRouter:

• The identifier used to perform the lookup (for example: userId, IP address, or login ID).
• The attributes your API will return.
• The API endpoint the Enrichment Service should call.
• Any authentication requirements for the API.
• The integrations that should receive decrypted values.

---

Step 2 — MetaRouter Configuration

Once the required details are provided:

1. MetaRouter will configure the enrichment endpoint on your cluster.
2. The Sync Injector will be configured to call the enrichment endpoint when necessary.
3. Secrets required to access your API will be securely stored.

---

Step 3 — Verify the Enrichment Request

Open your browser’s Developer Tools and select the Network tab.

Search for:

customEnrichment

Select the request and inspect the Payload.

Verify that:

• The correct identifier is being sent
• The request is reaching the enrichment endpoint
• The API response is returned successfully

---

Step 4 — Verify Event Payloads

Trigger an event on your site and inspect the event payload.

Look for the object:

context.provider.customEnrichment

If the enrichment values are present, they are ready to be mapped into integrations.

---

Step 5 — Map Enriched Values to Integrations

Add mappings within your integrations that reference the enrichment values.

Example input path:

context.provider.customEnrichment.<attribute>

Verify that integrations receiving decrypted values are configured correctly.

---

Troubleshooting

Checking if the Enrichment Service is Working

1. Open browser Developer Tools
2. Navigate to the Network tab
3. Search for:

customEnrichment

Inspect the request payload and verify the expected identifier is present.

Next:

• Trigger an event
• Inspect the event payload
• Confirm the enrichment values appear in:

context.provider.customEnrichment

---

Checking Decryption

Use the MetaRouter CLI Event Debugger to inspect processed events.

Look for:

enrichmentService

Values that appear decrypted within the debugger indicate the enrichment configuration is functioning properly.

---

{
  "code": 200,
  "data": { ... }
}

Unencrypted responses are only allowed for endpoints listed in:

allowedPlainEnrichmentEndpoints

---

Performance Constraints

The Enrichment Service is designed to avoid blocking analytics execution.

• Total sync timeout: 350ms
• Server response timeout: 300ms

If your enrichment API consistently exceeds these limits, optimization may be required.

---

FAQ

How long does the enrichment request take?

The total enrichment request timeout is 350ms, including a 300ms server response window.

If the API response exceeds this time, the enrichment request will fail gracefully to avoid delaying event collection.

---