AdsWizz

​

Cohort Activation on Web

// Retrieve Permutive cohorts from local storage
var permutiveCohorts = JSON.parse(localStorage.getItem('_padswizz')) || [];

// Retrieve Permutive user ID for impression tracking
var permutiveUserId = window.permutive.context.user_id || '';

// Construct your AdsWizz ad request URL
var adsWizzUrl = 'https://[YOUR_ADSWIZZ_DOMAIN]/adserver/...';

// Append Permutive cohorts as key-values
if (permutiveCohorts.length > 0) {
  adsWizzUrl += '&aw_0_1st.permutive=' + permutiveCohorts.join(',');
}

// Append Permutive user ID for impression tracking
if (permutiveUserId) {
  adsWizzUrl += '&aw_0_1st.permutiveid=' + permutiveUserId;
}

// Use the URL in your ad request
// (Implementation varies based on your player setup)

• The Permutive SDK automatically populates the _padswizz local storage field with activated cohort IDs
• Replace [YOUR_ADSWIZZ_DOMAIN] with your actual AdsWizz configuration
• All custom parameters must use the aw_0_1st prefix to identify first-party publisher data
• The same key-value format applies across all integration types (VAST, AIS, ORTB)
• Ensure your AdsWizz TAM has whitelisted these parameters

​

Advanced: Enable Impression Event Collection

1. Add Tracking Pixel to Ad/Creative: In your AdsWizz Audioserve campaigns, add the following tracking pixel to each Ad/Creative you want to track:

https://api.permutive.app/v2.0/px/track?k=PERMUTIVE_API_KEY&u=${parameters["aw_0_1st.permutiveid"]!}&e=AdsWizzImpression&p={"campaign_id":"{campaignID}","zone_id":"{ZoneId}","publisher_name":"{publishername}","listener_id":"{listenerid}","campaign_name":"{campaignName}","order_name":"{orderName}","advertiser_id":"{advertiserid}","advertiser_name":"{advertisername}"}

• Replace PERMUTIVE_API_KEY with your actual Permutive API key
• The macro ${parameters["aw_0_1st.permutiveid"]!} extracts the Permutive user ID from the ad request
• This requires the Permutive user ID to be passed in ad requests (see cohort activation code above)
• AdsWizz macros (e.g., {campaignID}, {ZoneId}) capture impression metadata

2. Available AdsWizz Macros: The following macros can be used to capture impression metadata:

• {campaignID} - Campaign ID
• {ZoneId} - Zone ID
• {publishername} - Publisher name
• {listenerid} - Listener ID (AdsWizz user ID - cookie on web, MAID/device ID in other environments)
• {campaignName} - Campaign name
• {orderName} - Order name
• {advertiserid} - Advertiser ID
• {advertisername} - Advertiser name

3. Custom Event Schema: Before implementing impression tracking, ensure your custom event schema has been configured in Permutive. Discuss with your Customer Success Manager to set this up.

​

Cohort Activation on iOS

// Import Permutive SDK
import Permutive

// Access AdsWizz Cohort IDs directly
let adsWizzCohorts: [String] = activations['adswizz_keyvalue']

// Retrieve Permutive user ID for impression tracking
let permutiveUserId = Permutive.user.id ?? ""

// Construct your AdsWizz ad request URL
var adsWizzUrl = "https://[YOUR_ADSWIZZ_DOMAIN]/adserver/..."

// Append Permutive cohorts as key-values
if !adsWizzCohorts.isEmpty {
    let cohortsString = adsWizzCohorts.joined(separator: ",")
    adsWizzUrl += "&aw_0_1st.permutive=\(cohortsString)"
}

// Append Permutive user ID for impression tracking
if !permutiveUserId.isEmpty {
    adsWizzUrl += "&aw_0_1st.permutiveid=\(permutiveUserId)"
}

// Use the URL in your ad request

• The activations property provides direct access to cohort IDs configured for AdsWizz activation
• Use the key adswizz_keyvalue to retrieve AdsWizz-specific cohorts
• Replace [YOUR_ADSWIZZ_DOMAIN] with your actual AdsWizz configuration
• All custom parameters must use the aw_0_1st prefix

​

Cohort Activation on Android

val triggerAction: TriggerAction = triggersProvider.cohortActivations(
    activationType = "adswizz_keyvalue",
    callback = object : Method<List<String>> {
        override fun invoke(cohorts: List<String>) {
            if (cohorts.isNotEmpty()) {
                // Cohorts available for AdsWizz activation
                // Pass these to your AdsWizz ad requests as key-values
                println("AdsWizz cohorts: $cohorts")
            } else {
                println("No active cohorts with an AdsWizz activation configured.")
            }
        }
    }
)

• The TriggersProvider API allows you to listen for cohort membership changes
• Use the activation type adswizz_keyvalue to retrieve AdsWizz-specific cohorts
• All custom parameters must use the aw_0_1st prefix
• See the Android SDK documentation for more details

​

Cohort Activation via API Direct

​

How it Works

1. Track events for a specific user (optional)
2. Retrieve cohort IDs for activation

curl --request POST \
     --url 'https://api.permutive.app/ccs/v1/segmentation?activations=true&synchronous-validation=false&k=PERMUTIVE_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "alias": {
    "tag": "example",
    "id": "12345"
  },
  "events": [
    {
      "name": "AudioView",
      "time": "2025-10-02T09:40:43.179Z",
      "view_id": "a55a9c8b-4a0b-4fe7-99a9-170624850501",
      "session_id": "1d145310-1338-4ff7-96dd-e6128f54cbe5",
      "properties": {
        "audio": {
          "title": "...",
          "genre": "..."
        }
      }
    }
  ]
}
'

• Account-linked (authenticated) users: Use an internal cross-platform user ID that identifies the user across your environments
• Non account-linked users: Use a device ID specific to the smart speaker
• AdsWizz listener ID: Can also be used as the identity alias

{
  "user_id": "2008c38f-dece-4570-976d-87593ed001c3",
  "cohorts": ["12345", "23456", "34567"],
  "activations": {
    "adswizz_keyvalue": ["12345"]
  }
}

• Replace PERMUTIVE_API_KEY with your actual Permutive API key
• The activations=true query parameter is required to receive activation data in the response

• Permutive collects IP addresses from your web users
• Cohort memberships are synced daily to AdsWizz server-to-server
• Cohorts appear as Audiences in AdsWizz, ready for campaign targeting
• Data syncing happens automatically once configured in the Permutive Dashboard

• Permutive must be collecting IP addresses from your web environment
• Work with your Permutive Customer Success Manager to ensure proper identity collection

• Permutive collects IDFA values from iOS users via the Permutive SDK
• Cohort memberships are synced daily to AdsWizz server-to-server
• Cohorts appear as Audiences in AdsWizz, ready for campaign targeting
• Data syncing happens automatically once configured in the Permutive Dashboard

• Permutive SDK must be deployed on your iOS app
• IDFA collection must be enabled and properly configured
• Users must grant tracking permission for IDFA to be available

• Permutive collects AAID values from Android users via the Permutive SDK
• Cohort memberships are synced daily to AdsWizz server-to-server
• Cohorts appear as Audiences in AdsWizz, ready for campaign targeting
• Data syncing happens automatically once configured in the Permutive Dashboard

• Permutive SDK must be deployed on your Android app
• AAID collection must be enabled and properly configured

• Permutive collects IP addresses from your smart speaker or server-side audio environments
• Cohort memberships are synced daily to AdsWizz server-to-server
• Cohorts appear as Audiences in AdsWizz, ready for campaign targeting
• Data syncing happens automatically once configured in the Permutive Dashboard

• Permutive must be collecting IP addresses from your smart speaker environment
• Work with your Permutive Customer Success Manager to ensure proper identity collection