AdsWizz

DirectionBidirectional

Environment

WebiOSAndroidCTVAPI Direct

Capability

Event CollectionCohort Activation

SDK RequiredYes

Product(s) RequiredCore Platform

AdsWizz is an audio advertising platform specializing in programmatic audio and podcast monetization.

Setup

Troubleshooting

Overview

AdsWizz is an audio advertising platform that specializes in programmatic audio and podcast monetization. The AdsWizz integration enables real-time cohort activation and ad impression event collection across audio environments including web players, mobile apps, CTV, and smart speakers. This integration is Bidirectional:

Source: Permutive collects ad impression events from AdsWizz Audioserve campaigns, enabling cohort creation based on audio ad delivery data.
Destination: Permutive cohorts are activated in AdsWizz ad requests via key-value pairs, with cohort IDs stored in local storage (Web) or retrieved via SDK APIs (iOS/Android) or API Direct (CTV/Smart Speakers).

Use cases include:

Activate Permutive cohorts in AdsWizz for real-time audience targeting across audio inventory.
Collect impression data from AdsWizz campaigns to build cohorts based on audio ad exposure.
Target audio campaigns using first-party data segments from Permutive.
Enable cross-environment activation across web players, mobile apps, smart speakers, and CTV.
Leverage key-value targeting in AdsWizz with Permutive cohorts for flexible campaign configuration.

Environment Compatibility

Environment	Supported	Notes
Web	Yes	Cohort IDs stored in `_padswizz` local storage key
iOS	Yes	Cohort IDs retrieved via `activations` property
Android	Yes	Cohort IDs retrieved via `TriggersProvider` API
CTV	Yes	Requires API Direct implementation
API Direct	Yes	For smart speakers, Alexa skills, and environments where SDK deployment isn’t feasible

Prerequisites

Permutive SDK or API Key: The Permutive SDK must be deployed (Web/iOS/Android) or you must have a Permutive API key for API Direct implementations.
AdsWizz Account: Active AdsWizz account with access to Audioserve.
AdsWizz Technical Account Manager Coordination: Publishers must notify their AdsWizz Technical Account Manager to whitelist custom parameters for reporting, targeting, and forecasting.
For Impression Tracking: A custom event schema must be configured in Permutive (discuss with your Customer Success Manager), and the Permutive user ID must be passed in ad requests.

Setup

Primary Setup Steps
Web
iOS
Android
API Direct

Enable Integration in Permutive Dashboard

Navigate to the integrations page in the Permutive dashboard (Settings → Integrations) and enable the AdsWizz integration.

Click Settings in the navigation menu
Select Integrations
Find AdsWizz in the integrations catalog
Click to enable the integration

Once enabled, you can activate individual cohorts for AdsWizz via cohort settings or the cohort activations page.

Coordinate with AdsWizz Technical Account Manager

Contact your AdsWizz Technical Account Manager to whitelist the custom parameters you’ll be passing.The key-value format for Permutive cohorts is:

Key: aw_0_1st.permutive
Value: Comma-separated cohort IDs

Additionally, notify them about the Permutive user ID parameter:

Key: aw_0_1st.permutiveid
Value: Permutive user ID

The aw_0_1st prefix identifies first-party data collected by the publisher. This coordination is essential to enable reporting, targeting, and forecasting options within AdsWizz.

Activate Cohorts

In the Permutive dashboard, activate cohorts for AdsWizz:

Navigate to the cohort you want to activate
Go to cohort settings or the cohort activations page
Enable the AdsWizz activation for that cohort

Activated cohort IDs will be made available in the appropriate storage location for each environment.

Implement Cohort Activation Code

Follow the environment-specific implementation steps in the tabs below (Web, iOS, Android) to retrieve cohort IDs and append them to AdsWizz ad requests.For CTV and Smart Speaker environments, see the API Direct implementation details in the Web tab.

Optional: Set up Impression Tracking

If you want to collect impression events from AdsWizz campaigns for cohort building and analytics, discuss this with your Customer Success Manager first.This requires:

A custom event schema to be set up within Permutive
Permutive user ID to be passed in AdsWizz ad requests (as aw_0_1st.permutiveid)
Tracking pixel placed in Ad/Creative in Audioserve campaigns

Once the event schema is configured, you can proceed with implementing the impression tracking pixel (see Web tab for details).

Cohort Activation on Web

To pass Permutive cohorts in your AdsWizz ad requests, retrieve cohort IDs from local storage and append them as key-value pairs to the ad request URL:

// 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)

Important Notes:

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

To collect impression events from AdsWizz for cohort building and analytics:

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}"}

Important Notes:

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

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

For the full list of supported macros, consult your AdsWizz Technical Account Manager.

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

Retrieve Permutive cohort IDs for AdsWizz using the activations property:

// 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

Important Notes:

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

Retrieve Permutive cohort IDs for AdsWizz using the TriggersProvider API. The callback is invoked whenever cohort membership changes:

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.")
            }
        }
    }
)

Once you have the cohort IDs, append them to your AdsWizz ad request URL as key-values using the format aw_0_1st.permutive=[cohort_ids].Important Notes:

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

In environments where it is not possible to deploy a Permutive SDK (e.g. some smart speaker environments), you can use Permutive’s CCS (Custom Cohort Segmentation) API for event tracking and segmentation instead.Access to this API requires customer-specific authorization. You will need a dedicated API key from Permutive.

How it Works

The CCS API can be used to:

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

The events array in the request is optional. If you only need to retrieve cohort memberships without tracking a new event, you can pass an empty array.

Example Request:

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": "..."
        }
      }
    }
  ]
}
'

The API accepts a user identity passed in the alias object. Permutive then either links this identity to an existing Permutive user ID or creates a new Permutive user ID if the identity hasn’t been seen before.Identity Options for Smart Speakers:

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

For cross-environment segmentation and targeting, the identity provided should be consistent with identities used in your other environments (web, app).Example Response:

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

The API response includes cohort IDs for AdsWizz activation under the adswizz_keyvalue key within the activations object. These can then be passed to AdsWizz as key-values for activation using the same format: aw_0_1st.permutive=[cohort_ids].Important Notes:

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

Data Types

With your AdsWizz integration setup, you’ll see the following additional event types collected in Permutive:

AdsWizz Impression

Fired when an audio ad impression is served through AdsWizz Audioserve. This event captures campaign, publisher, and listener metadata for cohort building and analytics.

campaign_id

string

The ID of the campaign associated with the impression.

zone_id

string

The ID of the zone where the ad was served.

publisher_name

string

The name of the publisher associated with the impression.

listener_id

string

The AdsWizz listener ID (cookie on web, MAID/device ID in other environments).

campaign_name

string

The name of the campaign associated with the impression.

order_name

string

The name of the order associated with the impression.

advertiser_id

string

The ID of the advertiser associated with the impression.

advertiser_name

string

The name of the advertiser associated with the impression.

Impression events require additional setup. A custom event schema must be configured in Permutive (discuss with your Customer Success Manager), and the tracking pixel must be placed in Ad/Creative in Audioserve campaigns. See the “Advanced: Enable Impression Event Collection” section in Setup for implementation details.

Troubleshooting

Cohorts not appearing in local storage or SDK APIs

Symptoms: Cohort IDs are not appearing in _padswizz local storage (Web) or not returned by SDK APIs (iOS/Android).Solutions:

Verify the AdsWizz integration is enabled in the Permutive dashboard (Settings → Integrations)
Check that cohorts have been activated for AdsWizz in the Permutive dashboard (via cohort settings or cohort activations page)
Ensure the Permutive SDK is properly deployed and initialized
For Web, check browser developer tools → Application → Local Storage to verify the _padswizz key exists
For iOS/Android, verify you’re using the correct activation type key (adswizz_keyvalue)

Cohorts not being passed in ad requests

Symptoms: Permutive cohorts are not included in AdsWizz ad request URLs, or targeting doesn’t work as expected.Solutions:

Verify cohort IDs are being retrieved correctly from local storage (Web) or SDK APIs (iOS/Android)
Ensure the key-value format is correct: aw_0_1st.permutive=[cohort_ids]
Confirm the custom parameters are being appended to the AdsWizz ad request URL
Check that the Permutive SDK loads before the AdsWizz ad request is made
Verify the cohorts are activated with an AdsWizz activation (not just other activations)

AdsWizz not recognizing key-values (whitelisting issue)

Symptoms: Key-values are being passed in ad requests but AdsWizz is not recognizing them for targeting or reporting.Solutions:

Contact your AdsWizz Technical Account Manager to whitelist the custom parameters
Confirm that the aw_0_1st.permutive and aw_0_1st.permutiveid parameters have been whitelisted
Verify the key-value format matches AdsWizz requirements (prefix aw_0_1st for first-party data)
Allow time for whitelisting changes to take effect in AdsWizz systems
Check AdsWizz campaign targeting interface to confirm parameters are available

Impression events not being collected

Symptoms: AdsWizz impression events are not appearing in Permutive analytics or event stream.Solutions:

Verify the tracking pixel has been added to Ad/Creative in AdsWizz Audioserve campaigns
Ensure the custom event schema has been configured in Permutive (discuss with your Customer Success Manager)
Confirm the Permutive user ID is being passed in ad requests (as aw_0_1st.permutiveid)
Check that the tracking pixel URL is correctly formatted with the Permutive API key
Verify AdsWizz macros are correctly replacing with actual values (e.g., {campaignID}, {ZoneId})
Test the tracking pixel URL manually to confirm it’s reachable

API Direct returning empty activations

Symptoms: The CCS API response includes an empty adswizz_keyvalue array or doesn’t include the key at all.Solutions:

Verify the AdsWizz integration is enabled in the Permutive dashboard
Check that cohorts have been activated for AdsWizz
Ensure the user identified in the API request (via alias) is a member of activated cohorts
Confirm the activations=true query parameter is included in the API request URL
Allow time for cohort membership to be computed after sending events
Verify the API key used in the request has the correct permissions

Changelog

October 2025

AdsWizz key-value integration released for Web, iOS, and Android environments
Added support for API Direct implementation for CTV and smart speaker environments
Enabled AdsWizz impression event collection via tracking pixel

For detailed changelog information, visit our Changelog.

Integrations

Identity

Contextual

Advertising

Marketing

Data Collaboration

Video

Social Media

Survey

AdsWizz

AdsWizz

Setup

Troubleshooting

Overview

Environment Compatibility

Prerequisites

Setup

Cohort Activation on Web

Advanced: Enable Impression Event Collection

Cohort Activation on iOS

Cohort Activation on Android

Cohort Activation via API Direct

How it Works

Data Types

Troubleshooting

Changelog

October 2025

Integrations

Identity

Contextual

Advertising

Marketing

Data Collaboration

Video

Social Media

Survey

​AdsWizz

Setup

Troubleshooting

​Overview

​Environment Compatibility

​Prerequisites

​Setup

​Cohort Activation on Web

​Advanced: Enable Impression Event Collection

​Cohort Activation on iOS

​Cohort Activation on Android

​Cohort Activation via API Direct

​How it Works

​Data Types

​Troubleshooting

​Changelog

​October 2025

AdsWizz

Overview

Environment Compatibility

Prerequisites

Setup

Cohort Activation on Web

Advanced: Enable Impression Event Collection

Cohort Activation on iOS

Cohort Activation on Android

Cohort Activation via API Direct

How it Works

Data Types

Troubleshooting

Changelog

October 2025