> ## Documentation Index
> Fetch the complete documentation index at: https://docs.permutive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AdsWizz

> Integrate with AdsWizz for audio advertising and cohort activation.

export const NoBadge = () => {
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.5rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: '#F7D0E2',
    color: '#1A1A1A',
    fontWeight: '500'
  }}>
      No
    </span>;
};

export const YesBadge = () => {
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.5rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: '#C7E8F9',
    color: '#1A1A1A',
    fontWeight: '500'
  }}>
      Yes
    </span>;
};

export const BadgeRowCenter = ({label, children}) => {
  return <div style={{
    display: 'flex',
    justifyContent: 'space-between',
    alignItems: 'center',
    marginBottom: '0.5rem'
  }}>
      <span style={{
    fontSize: '0.625rem',
    color: '#6b7280',
    textTransform: 'uppercase',
    fontWeight: '500',
    letterSpacing: '0.05em'
  }}>
        {label}
      </span>
      {children}
    </div>;
};

export const BadgeRow = ({label, children}) => {
  return <div style={{
    display: 'flex',
    justifyContent: 'space-between',
    alignItems: 'flex-start',
    marginBottom: '0.5rem'
  }}>
      <span style={{
    fontSize: '0.625rem',
    color: '#6b7280',
    textTransform: 'uppercase',
    fontWeight: '500',
    letterSpacing: '0.05em'
  }}>
        {label}
      </span>
      {children}
    </div>;
};

export const BadgeContainer = ({children}) => {
  return <div style={{
    display: 'flex',
    gap: '0.25rem',
    flexWrap: 'wrap',
    justifyContent: 'flex-end',
    minWidth: '0',
    flex: '1'
  }}>
      {children}
    </div>;
};

export const ProductRequiredBadge = ({product}) => {
  const getBadgeStyle = product => {
    switch (product) {
      case 'Core Platform':
        return {
          background: '#CB88FC',
          color: '#1A1A1A'
        };
        --purple;
      case 'Routing':
        return {
          background: '#CB88FC',
          color: '#1A1A1A'
        };
        --purple;
      case 'Contextual':
        return {
          background: '#CB88FC',
          color: '#1A1A1A'
        };
        --purple;
      default:
        return {
          background: '#A7B3D9',
          color: '#1A1A1A'
        };
        --haze;
    }
  };
  const style = getBadgeStyle(product);
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.375rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: style.background,
    color: style.color,
    fontWeight: '500'
  }}>
      {product}
    </span>;
};

export const SdkRequiredBadge = ({required}) => {
  const getBadgeStyle = required => {
    switch (required) {
      case 'Yes':
        return {
          background: '#C7E8F9',
          color: '#1A1A1A'
        };
        --blue;
      case 'No':
        return {
          background: '#F7D0E2',
          color: '#1A1A1A'
        };
        --pink;
      default:
        return {
          background: '#A7B3D9',
          color: '#1A1A1A'
        };
        --haze;
    }
  };
  const style = getBadgeStyle(required);
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.375rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: style.background,
    color: style.color,
    fontWeight: '500'
  }}>
      {required}
    </span>;
};

export const CapabilityBadge = ({capability}) => {
  const getBadgeStyle = capability => {
    switch (capability) {
      case 'Event Collection':
        return {
          background: '#EFDFC8',
          color: '#1A1A1A'
        };
        --clay;
      case 'Cohort Activation':
        return {
          background: '#EFDFC8',
          color: '#1A1A1A'
        };
        --clay;
      case 'Campaign Optimization':
        return {
          background: '#EFDFC8',
          color: '#1A1A1A'
        };
        --clay;
      case 'Identity Signal':
        return {
          background: '#EFDFC8',
          color: '#1A1A1A'
        };
        --clay;
      case 'Contextual Signal':
        return {
          background: '#EFDFC8',
          color: '#1A1A1A'
        };
        --clay;
      case 'Connectivity':
        return {
          background: '#EFDFC8',
          color: '#1A1A1A'
        };
        --clay;
      case 'Routing':
        return {
          background: '#EFDFC8',
          color: '#1A1A1A'
        };
        --clay;
      case 'Data Collaboration':
        return {
          background: '#EFDFC8',
          color: '#1A1A1A'
        };
        --clay;
      default:
        return {
          background: '#A7B3D9',
          color: '#1A1A1A'
        };
        --haze;
    }
  };
  const style = getBadgeStyle(capability);
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.375rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: style.background,
    color: style.color,
    fontWeight: '500',
    whiteSpace: 'nowrap'
  }}>
      {capability}
    </span>;
};

export const EnvironmentBadge = ({environment}) => {
  const getBadgeStyle = environment => {
    switch (environment) {
      case 'Web':
        return {
          background: '#F9C1A8',
          color: '#1A1A1A'
        };
        --peach;
      case 'iOS':
        return {
          background: '#F9C1A8',
          color: '#1A1A1A'
        };
        --peach;
      case 'Android':
        return {
          background: '#F9C1A8',
          color: '#1A1A1A'
        };
        --peach;
      case 'CTV':
        return {
          background: '#F9C1A8',
          color: '#1A1A1A'
        };
        --peach;
      case 'API Direct':
        return {
          background: '#F9C1A8',
          color: '#1A1A1A'
        };
        --peach;
      default:
        return {
          background: '#A7B3D9',
          color: '#1A1A1A'
        };
        --haze;
    }
  };
  const style = getBadgeStyle(environment);
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.375rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: style.background,
    color: style.color,
    fontWeight: '500',
    whiteSpace: 'nowrap'
  }}>
      {environment}
    </span>;
};

export const DirectionBadge = ({direction}) => {
  const getBadgeStyle = direction => {
    switch (direction) {
      case 'Bidirectional':
        return {
          background: '#FA8784',
          color: '#1A1A1A'
        };
        --tomato;
      case 'Destination':
        return {
          background: '#FA8784',
          color: '#1A1A1A'
        };
        --tomato;
      case 'Source':
        return {
          background: '#FA8784',
          color: '#1A1A1A'
        };
        --tomato;
      default:
        return {
          background: '#A7B3D9',
          color: '#1A1A1A'
        };
        --haze;
    }
  };
  const style = getBadgeStyle(direction);
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.375rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: style.background,
    color: style.color,
    fontWeight: '500'
  }}>
      {direction}
    </span>;
};

<Card title="">
  <div style={{ display: 'flex', alignItems: 'center', marginBottom: '1rem' }}>
    <div style={{ width: '32px', height: '32px', marginRight: '0.75rem', display: 'flex', alignItems: 'center', justifyContent: 'center', flexShrink: 0 }}>
      <img src="https://mintcdn.com/permutive/pNhz39ducTVcQczh/images/integrations/logos/adswizz.svg?fit=max&auto=format&n=pNhz39ducTVcQczh&q=85&s=872eda08cf80a878d44bf1d34744add8" alt="AdsWizz" style={{ maxWidth: '32px', maxHeight: '32px', display: 'block' }} width="102" height="93" data-path="images/integrations/logos/adswizz.svg" />
    </div>

    <h3 style={{ margin: 0, fontSize: '1.125rem', fontWeight: '600' }}>AdsWizz</h3>
  </div>

  <div style={{ marginBottom: '1rem' }}>
    <BadgeRowCenter label="Direction">
      <DirectionBadge direction="Bidirectional" />
    </BadgeRowCenter>

    <BadgeRowCenter label="Environment">
      <BadgeContainer>
        <EnvironmentBadge environment="Web" />

        <EnvironmentBadge environment="iOS" />

        <EnvironmentBadge environment="Android" />

        <EnvironmentBadge environment="API Direct" />
      </BadgeContainer>
    </BadgeRowCenter>

    <BadgeRowCenter label="Capability">
      <BadgeContainer>
        <CapabilityBadge capability="Event Collection" />

        <CapabilityBadge capability="Cohort Activation" />
      </BadgeContainer>
    </BadgeRowCenter>

    <BadgeRowCenter label="SDK Required">
      <SdkRequiredBadge required="Yes" />
    </BadgeRowCenter>

    <BadgeRowCenter label="Product(s) Required">
      <ProductRequiredBadge product="Core Platform" />
    </BadgeRowCenter>
  </div>

  <p style={{ margin: 0, fontSize: '0.875rem', color: '#6b7280', lineHeight: '1.5' }}>
    AdsWizz is an audio advertising platform specializing in programmatic audio and podcast monetization.
  </p>
</Card>

<CardGroup cols={2}>
  <Card title="Setup" href="#setup" icon="gear" />

  <Card title="Troubleshooting" href="#troubleshooting" icon="wrench" />
</CardGroup>

## 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, 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 for campaign targeting in AdsWizz. This integration supports two distinct activation methods:

**Key-Value Activation:** Real-time cohort activation via key-value targeting (Web, iOS, Android, API Direct). Cohort IDs are stored in local storage (Web), retrieved via SDK APIs (iOS/Android), or returned from the CCS API (API Direct), then appended to AdsWizz ad requests using the `aw_0_1st.permutive` custom parameter.

**Identity Based Activation:** Server-to-server cohort activation where Permutive uploads audience data enriched with cohort memberships to AdsWizz, keyed by identity tags such as IDFA, AAID, and IP Address. See [Supported Identity Tags](#supported-identity-tags) for the full list. Cohorts appear as Audiences in AdsWizz.

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, and smart speakers.
* Activate audiences in environments without an SDK using identity-based, server-to-server delivery (Identity Based).
* Leverage key-value targeting in AdsWizz with Permutive cohorts for flexible campaign configuration.

## Choosing an Activation Method

AdsWizz supports two activation methods. Choose the method that best fits your use case:

| Aspect              | Key-Value Activation                                                 | Identity Based Activation                                                            |
| ------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| **Mechanism**       | Client-side, cohort IDs appended to ad requests                      | Server-to-server transfer                                                            |
| **Environments**    | Web, iOS, Android, API Direct                                        | Web, iOS, Android, API Direct (Smart Speakers)                                       |
| **Sync Timing**     | Real-time                                                            | Daily                                                                                |
| **AdsWizz Feature** | Key-value targeting (`aw_0_1st.permutive`)                           | Audiences                                                                            |
| **Use Cases**       | Real-time targeting on owned audio inventory across all environments | Audience activation in environments without an SDK, cross business unit data sharing |

## Environment Compatibility

The table below shows which activation method is available for each environment:

| Environment    | Key-Value Activation | Identity Based Activation |
| -------------- | -------------------- | ------------------------- |
| **Web**        | <YesBadge />         | <YesBadge />              |
| **iOS**        | <YesBadge />         | <YesBadge />              |
| **Android**    | <YesBadge />         | <YesBadge />              |
| **API Direct** | <YesBadge />         | <YesBadge />              |

<Note>
  **API Direct** covers smart speakers, Alexa skills, and other environments where SDK deployment isn't feasible. For Identity Based Activation in these environments, IP address is used as the identity tag.
</Note>

## Supported Identity Tags

These identity tags apply to **Identity Based Activation** only — Permutive uploads cohort memberships to AdsWizz keyed by the identifiers below. (Key-Value Activation does not use identity tags; it appends cohort IDs to ad requests client-side.)

| Identity Tag (`tag`) | Description                             | Environment                                                    |
| -------------------- | --------------------------------------- | -------------------------------------------------------------- |
| `idfa`               | Apple Identifier for Advertisers (IDFA) | iOS                                                            |
| `aaid`               | Android Advertising ID (AAID)           | Android                                                        |
| `ip_address`         | IP Address                              | Web, smart speakers, and other environments without device IDs |

<Note>
  Identity Based Activation requires that Permutive is collecting the identity tags you select. Work with your Permutive Customer Success Manager to ensure identity collection is configured properly for your desired tags.
</Note>

## Prerequisites

**For Key-Value Activation:**

* **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.

**For Identity Based Activation:**

* **AdsWizz Account**: Active AdsWizz account with access to Audioserve.
* **Permutive Identity Collection**: Identity collection must be configured in Permutive for the identity tags you want to send (see [Supported Identity Tags](#supported-identity-tags)).
* **AdsWizz Technical Account Manager Coordination**: Publishers must coordinate with their AdsWizz Technical Account Manager to initiate the technical setup. AdsWizz provisions a bucket/path that Permutive uses to upload audience data files on the customer's behalf.
* **Integration Enablement**: Identity Based Activation is enabled by Permutive on request. Contact your Customer Success Manager to discuss enablement and timelines.

## Setup

### Key-Value Activation

<Tabs>
  <Tab title="Primary Setup Steps">
    <Steps>
      <Step title="Enable Integration in Permutive Dashboard">
        Navigate to the integrations page in the Permutive dashboard (Settings → Integrations) and enable the AdsWizz integration.

        1. Click **Settings** in the navigation menu
        2. Select **Integrations**
        3. Find **AdsWizz** in the integrations catalog
        4. Click to enable the integration

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

      <Step title="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.
      </Step>

      <Step title="Activate Cohorts">
        In the Permutive dashboard, activate cohorts for AdsWizz:

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

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

      <Step title="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 Smart Speaker environments, see the API Direct implementation details in the Web tab.
      </Step>

      <Step title="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).
      </Step>
    </Steps>
  </Tab>

  <Tab title="Web">
    ## 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:

    ```javascript theme={"dark"}
    // 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:

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

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

    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

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

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

  <Tab title="iOS">
    ## Cohort Activation on iOS

    Retrieve Permutive cohort IDs for AdsWizz using the `activations` property:

    ```swift theme={"dark"}
    // 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
  </Tab>

  <Tab title="Android">
    ## Cohort Activation on Android

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

    ```kotlin theme={"dark"}
    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](https://sdk-docs.permutive.com/core/com.permutive.android/-triggers-provider/query-reactions.html) for more details
  </Tab>

  <Tab title="API Direct">
    ## 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:

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

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

    **Example Request:**

    ```bash theme={"dark"}
    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:**

    ```json theme={"dark"}
    {
      "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
  </Tab>
</Tabs>

### Identity Based Activation

<Tabs>
  <Tab title="Primary Setup Steps">
    <Steps>
      <Step title="Contact Permutive CSM">
        Contact your Permutive Customer Success Manager to enable Identity Based Activation for AdsWizz. This is a server-to-server integration that must be configured by Permutive.
      </Step>

      <Step title="Coordinate with AdsWizz Technical Account Manager">
        Contact your AdsWizz Technical Account Manager to initiate the technical setup on the AdsWizz side. AdsWizz provisions a bucket/path that Permutive uses to upload audience data files on your behalf, and shares the destination details with Permutive.
      </Step>

      <Step title="Configure in Permutive Dashboard">
        Once enabled, navigate to Settings → Integrations in the Permutive Dashboard. Find "AdsWizz (ID-based)" in the list of available integrations and click to configure it.
      </Step>

      <Step title="Select Identity Tags">
        Choose which identity tags you want to send to AdsWizz.

        See [Supported Identity Tags](#supported-identity-tags) for all available types. Select the tags that match your use case and the environments where you need activation.
      </Step>

      <Step title="Save Configuration">
        Save your configuration. Permutive will begin syncing cohort data to AdsWizz on a daily basis for users with the selected identity types.
      </Step>

      <Step title="Activate Cohorts">
        Navigate to your cohorts in the Permutive Dashboard and enable the "AdsWizz (ID-based)" activation toggle for each cohort you want to sync to AdsWizz.
      </Step>

      <Step title="Verify in AdsWizz">
        After the first sync completes (within 24 hours), check your AdsWizz dashboard to verify that audiences appear with names matching your activated cohorts.
      </Step>
    </Steps>

    <Info>
      Cohort data syncs to AdsWizz daily. Changes to cohort membership will be reflected in AdsWizz within 24 hours of the next scheduled sync.
    </Info>

    <Note>
      Identity Based Activation for AdsWizz is enabled by Permutive on request. The integration approach has been mapped out with AdsWizz and can be made available within a few weeks of a customer request. Contact your Customer Success Manager to get started.
    </Note>
  </Tab>

  <Tab title="Web">
    Identity Based Activation for Web enables server-to-server cohort syncing using IP Address. No SDK code changes are required to append cohorts to ad requests — activation happens server-to-server.

    **How it works:**

    * 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

    **Prerequisites:**

    * Permutive must be collecting IP addresses from your web environment
    * Work with your Permutive Customer Success Manager to ensure proper identity collection
  </Tab>

  <Tab title="iOS">
    Identity Based Activation for iOS enables server-to-server cohort syncing using IDFA (Identifier for Advertisers). No SDK code changes are required on iOS devices.

    **How it works:**

    * 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

    **Prerequisites:**

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

  <Tab title="Android">
    Identity Based Activation for Android enables server-to-server cohort syncing using AAID (Android Advertising ID). No SDK code changes are required on Android devices.

    **How it works:**

    * 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

    **Prerequisites:**

    * Permutive SDK must be deployed on your Android app
    * AAID collection must be enabled and properly configured
  </Tab>

  <Tab title="Smart Speakers">
    Identity Based Activation for smart speakers and other server-side audio environments enables server-to-server cohort syncing using IP Address. No SDK deployment is required in the activation environment.

    **How it works:**

    * 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

    **Prerequisites:**

    * Permutive must be collecting IP addresses from your smart speaker environment
    * Work with your Permutive Customer Success Manager to ensure proper identity collection
  </Tab>
</Tabs>

## Data Types

The AdsWizz integration involves the following data types. Impression events are collected into Permutive (Source), while cohort activation data is delivered to AdsWizz (Destination):

<AccordionGroup>
  <Accordion title="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.

    <ResponseField name="campaign_id" type="string">
      The ID of the campaign associated with the impression.
    </ResponseField>

    <ResponseField name="zone_id" type="string">
      The ID of the zone where the ad was served.
    </ResponseField>

    <ResponseField name="publisher_name" type="string">
      The name of the publisher associated with the impression.
    </ResponseField>

    <ResponseField name="listener_id" type="string">
      The AdsWizz listener ID (cookie on web, MAID/device ID in other environments).
    </ResponseField>

    <ResponseField name="campaign_name" type="string">
      The name of the campaign associated with the impression.
    </ResponseField>

    <ResponseField name="order_name" type="string">
      The name of the order associated with the impression.
    </ResponseField>

    <ResponseField name="advertiser_id" type="string">
      The ID of the advertiser associated with the impression.
    </ResponseField>

    <ResponseField name="advertiser_name" type="string">
      The name of the advertiser associated with the impression.
    </ResponseField>
  </Accordion>

  <Accordion title="Cohort Activation Data (Identity Based)">
    When you activate a cohort using Identity Based Activation, Permutive uploads audience data enriched with cohort memberships to AdsWizz via a server-to-server transfer.

    **Data Transfer:**

    * Cohort data is synced daily from Permutive to AdsWizz
    * Data is keyed by the identity tags you selected during configuration (see [Supported Identity Tags](#supported-identity-tags))
    * Each user's cohort memberships are associated with their identity values

    **AdsWizz Audiences:**

    * Cohorts appear as Audiences in AdsWizz
    * Named using the cohort name from Permutive
    * Available for campaign targeting in AdsWizz's audience targeting interface
    * Updated daily with the latest cohort membership data
  </Accordion>
</AccordionGroup>

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

## Troubleshooting

<AccordionGroup>
  <Accordion title="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`)
  </Accordion>

  <Accordion title="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)
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Issues with Identity Based Activation">
    **Symptoms:** Audiences are not appearing in AdsWizz, or cohort memberships are not syncing as expected.

    **Solutions:**

    * Verify that cohorts are activated with the "AdsWizz (ID-based)" toggle enabled in the Permutive Dashboard
    * Remember that cohort data syncs daily — allow up to 24 hours for changes to appear in AdsWizz
    * Confirm that Permutive is collecting the identity tags you selected (see [Supported Identity Tags](#supported-identity-tags)) by checking with your Permutive Customer Success Manager
    * Verify your selected identity tags are correct in Settings → Integrations
    * Confirm Identity Based Activation has been enabled for your workspace (this is enabled by Permutive on request)

    For Identity Based Activation issues, contact your Permutive Customer Success Manager for assistance.
  </Accordion>
</AccordionGroup>

## Changelog

### June 2026

* Documented Identity Based Activation for AdsWizz: server-to-server cohort upload keyed by IDFA, AAID, or IP Address, with cohorts appearing as Audiences in AdsWizz (available on request)

### October 2025

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

<Info>
  For detailed changelog information, visit our [Changelog](https://changelog.permutive.com/).
</Info>