wip - permutive

Author: ChristianPavilonis

crates/common/src/settings.rs

@@ -79,6 +79,24 @@ fn default_auto_configure() -> bool {
     true
 }
 
+#[derive(Debug, Default, Deserialize, Serialize, Validate)]
+pub struct Permutive {
+    #[serde(default)]
+    pub project_id: String,
+    #[serde(default)]
+    pub workspace_id: String,
+    #[serde(default = "default_permutive_auto_configure")]
+    pub auto_configure: bool,
+    #[serde(default)]
+    pub proxy_events: bool,
+    #[serde(default)]
+    pub proxy_sync: bool,
+}
+
+fn default_permutive_auto_configure() -> bool {
+    true
+}
+
 #[allow(unused)]
 #[derive(Debug, Default, Deserialize, Serialize, Validate)]
 pub struct Synthetic {
@@ -131,6 +149,8 @@ pub struct Settings {
     #[validate(nested)]
     pub prebid: Prebid,
     #[validate(nested)]
+    pub permutive: Permutive,
+    #[validate(nested)]
     pub synthetic: Synthetic,
     #[serde(default, deserialize_with = "vec_from_seq_or_map")]
     #[validate(nested)]

crates/common/src/test_support.rs

@@ -19,6 +19,13 @@ pub mod tests {
             [prebid]
             server_url = "https://test-prebid.com/openrtb2/auction"  
 
+            [permutive]
+            project_id = "test-project-123"
+            workspace_id = "test-workspace"
+            auto_configure = true
+            proxy_events = true
+            proxy_sync = true
+
             [synthetic] 
             counter_store = "test-counter-store"
             opid_store = "test-opid-store"

permutive-callstack.md

@@ -0,0 +1,73 @@
+# Permutive call stack analysis
+
+(Analysis generated from HAR file `autoblog-permutive.har`)
+
+### Overview
+
+This HAR trace includes several network requests to **Permutive**, a data management and analytics platform used for audience segmentation, consent management, and advertising personalization. The trace shows that Autoblog’s site integrates Permutive both as a **CDN-loaded JavaScript library** and through **backend API endpoints** for event tracking and user synchronization.
+
+### Step-by-step breakdown
+
+#### 1. Script loading
+
+* **URL example:** `https://cdn.permutive.com/autoblog/xyz123-web.js`
+* **Purpose:** The browser first downloads a JavaScript SDK from the Permutive CDN. This script initializes the Permutive runtime within the page, sets up event listeners, and reads any stored identifiers or consent tokens from local storage or cookies.
+* **What happens next:** Once loaded, the script queues initial events (page view, user session) and loads configuration from Permutive’s project settings.
+
+#### 2. Initialization call
+
+* **URL example:** `https://api.permutive.com/v2/projects/abc123/config`
+* **Purpose:** Fetches configuration for the Autoblog project. This includes project ID, enabled modules (segmentation, identity sync, publisher integrations), and sampling rules.
+* **Data sent:** Usually minimal—mostly the site’s project key, environment, and SDK version.
+* **Data received:** A JSON configuration that defines which segments, events, and partner pixels should be active.
+
+#### 3. Event collection
+
+* **URL example:** `https://events.permutive.app/collect`
+* **Purpose:** Sends event payloads such as `pageView`, `contentView`, or custom behavioral events triggered by the SDK.
+* **Data sent:** Contains anonymous or pseudonymous identifiers (UUIDs or hashed IDs), timestamps, event names, and contextual metadata (page category, article ID, user device type, etc.).
+* **Response:** Usually a 204 No Content—server simply acknowledges receipt.
+
+#### 4. Identity synchronization
+
+* **URL example:** `https://sync.permutive.com/v1/sync`
+* **Purpose:** Syncs user IDs with external partners (e.g., The Trade Desk, Google, or other SSP/DSPs). This allows ad systems to align audience segments.
+* **Data sent:** Includes a unique Permutive user ID and partner IDs if already known. Sometimes cookies like `_puid` or `_permutive-id` are referenced.
+* **Response:** Often returns JSON mapping or triggers redirects to partner sync URLs.
+
+#### 5. Segment updates
+
+* **URL example:** `https://api.permutive.com/v1/segments`
+* **Purpose:** Requests or updates which audience segments the current user belongs to based on prior behavior.
+* **Data sent:** Permutive user ID, project ID, and event triggers.
+* **Response:** A JSON array of active segment identifiers.
+
+#### 6. Local storage interaction
+
+* **Client-side actions:** The Permutive SDK stores data locally under keys like `permutive-id`, `permutive-session`, and `permutive-segments`.
+* **Purpose:** These persist user identifiers across visits and allow real-time targeting without re-fetching from the API each time.
+
+### Overall flow summary
+
+1. **CDN script loads** and boots the SDK.
+2. **Configuration fetched** to understand which events and integrations to run.
+3. **Events collected** and sent to the `/collect` endpoint.
+4. **Segments synced** and updated locally.
+5. **Partner syncs** propagate IDs to external ad networks.
+
+### Components involved
+
+| Component               | Role                            | Notes                                       |
+| ----------------------- | ------------------------------- | ------------------------------------------- |
+| `cdn.permutive.com`     | Hosts JavaScript SDK            | Static script defining client logic         |
+| `api.permutive.com`     | Configuration & segment updates | Used during initialization and segmentation |
+| `events.permutive.app`  | Event collection endpoint       | Receives behavioral events                  |
+| `sync.permutive.com`    | Identity synchronization        | Connects to partner ad systems              |
+| Local Storage & Cookies | Client persistence              | Keeps user/session data between visits      |
+
+### In short
+
+The call stack represents a typical **client-side DMP workflow**:
+
+* Initialization → Configuration → Event Logging → Audience Segmentation → ID Synchronization.
+* No direct page interception occurs (no `preventDefault` on links), but the SDK may hook into analytics events for navigation or engagement tracking.

trusted-server.toml

@@ -16,6 +16,13 @@ bidders = ["kargo", "rubicon", "appnexus", "openx"]
 auto_configure = false
 debug = false
 
+[permutive]
+project_id = ""
+workspace_id = ""
+auto_configure = true
+proxy_events = true
+proxy_sync = true
+
 [synthetic]
 counter_store = "counter_store"
 opid_store = "opid_store"