> ## 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="CTV" />

        <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, 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**        | <YesBadge /> | Cohort IDs stored in `_padswizz` local storage key                                     |
| **iOS**        | <YesBadge /> | Cohort IDs retrieved via `activations` property                                        |
| **Android**    | <YesBadge /> | Cohort IDs retrieved via `TriggersProvider` API                                        |
| **CTV**        | <YesBadge /> | Requires API Direct implementation                                                     |
| **API Direct** | <YesBadge /> | 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

<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 CTV and 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>

## Data Types

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

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

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

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