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

# TikTok

> Integrate with TikTok for cohort activation and audience targeting

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/tiktok.svg?fit=max&auto=format&n=pNhz39ducTVcQczh&q=85&s=5227b28b9a51eca078085882cb43d83b" alt="TikTok" style={{ maxWidth: '32px', maxHeight: '32px', display: 'block', backgroundColor: '#f3f4f6', borderRadius: '4px', padding: '2px' }} width="968" height="938" data-path="images/integrations/logos/tiktok.svg" />
    </div>

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

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

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

    <BadgeRowCenter label="Capability">
      <BadgeContainer>
        <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",
}}
  >
    TikTok is a leading social media platform for short-form video content.
    Permutive's integration enables publishers to activate cohorts for targeted
    advertising on TikTok Ads Manager.
  </p>
</Card>

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

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

## Overview

TikTok is a global social media platform that allows users to create, share, and discover short-form video content. Our integration with TikTok enables publishers to activate Permutive cohorts for targeted advertising campaigns on TikTok Ads Manager.

This integration is a Destination:

* **Destination:** Permutive can activate your cohorts in TikTok for audience targeting and campaign optimization.

Use cases include:

* Activate Permutive cohorts in TikTok Ads Manager to build custom audiences for targeted advertising campaigns
* Leverage hashed email matching to improve match rates and reduce reliance on third-party cookies
* Create lookalike audiences in TikTok based on your Permutive cohorts
* Export user lists from Permutive for manual upload to TikTok as custom audiences

## Environment Compatibility

| Environment    | Supported    | Notes                                             |
| -------------- | ------------ | ------------------------------------------------- |
| **Web**        | <YesBadge /> | Requires TikTok Pixel installed on site           |
| **iOS**        | <NoBadge />  | User export with IDFA supported via manual upload |
| **Android**    | <NoBadge />  | User export with GAID supported via manual upload |
| **CTV**        | <NoBadge />  | --                                                |
| **API Direct** | <NoBadge />  | --                                                |

## Prerequisites

* **TikTok Pixel Installed**: You must have the TikTok Pixel installed on your website. The pixel should be available as a global object (`ttq`). To verify, open your browser console and run `ttq` - you should see the TikTok Analytics object.
* **TikTok Ads Manager Account**: You must have an active TikTok Ads Manager account with permissions to create custom audiences.
* **User Alias Collection**: You must be collecting at least one of the following user aliases via Permutive's identity framework for enhanced matching:
  * Hashed email address (SHA-256)
  * Hashed mobile number (SHA-256)
  * IDFA (Identifier for Advertisers)
  * GAID (Google Advertising ID)

<Note>
  Phone and email matching in TikTok may require coordination with your TikTok
  Account Manager. Advanced Matching via email and phone number takes precedence
  over matching via IP address and user agent.
</Note>

## Setup

<Tabs>
  <Tab title="Primary Setup Steps">
    <Steps>
      <Step title="Enable in Permutive Dashboard">
        Contact your Customer Success Manager to enable the TikTok integration for your workspace. Once enabled, navigate to your cohort configuration page in the Permutive Dashboard.
      </Step>

      <Step title="Activate Cohorts for TikTok">
        For each cohort you want to activate in TikTok, toggle on the TikTok activation. You can enable this when creating a new cohort or by editing an existing cohort.

        When a user enters a cohort that has TikTok activation enabled, Permutive will fire a pixel event via the installed TikTok Pixel. The event name will have the format `Permutive-{cohort_code}` where `{cohort_code}` is your cohort's unique identifier.
      </Step>

      <Step title="Create Custom Audience in TikTok Ads Manager">
        In TikTok Ads Manager, navigate to Tools → Events to verify that Permutive events are being received. Then create a custom audience:

        1. Go to your TikTok Ads Manager
        2. Navigate to Assets → Audiences
        3. Click "Create Audience" → "Custom Audience"
        4. Select "Website Activity"
        5. Choose your TikTok Pixel
        6. Select the Permutive events corresponding to your cohorts (e.g., `Permutive-1234`)
        7. Configure your audience retention period (default is 30 days)
        8. Save your custom audience

        For detailed instructions, refer to the [TikTok Custom Audiences documentation](https://ads.tiktok.com/help/article/custom-audiences).
      </Step>

      <Step title="Verify Setup">
        In TikTok Ads Manager, navigate to Tools → Events. You should see Permutive events appearing in the event list. Check that the events correspond to your activated cohorts.

        In the Audience Library, verify that your custom audiences are populating with matched users.
      </Step>
    </Steps>

    <Expandable title="Alternative: User Export for Manual Upload">
      ### User Export Setup

      If you prefer to manually export user lists and upload them to TikTok (useful for mobile app audiences or file-based matching):

      <Steps>
        <Step title="Create User Export in Permutive">
          In the Permutive Dashboard, navigate to Cohort Activations → Exports and
          click "Add Export". Configure your export: - **ID Type**: Select the
          identifier type for matching (email\_sha256, mob\_sha256, IDFA, or GAID) -
          **Date Range**: Specify the time period for users to include - **Segments**:
          Select the cohorts you want to export for TikTok targeting
        </Step>

        <Step title="Download Export File">
          Once the export is generated, download the file containing your user
          identifiers.
        </Step>

        <Step title="Upload to TikTok as Customer File">
          In TikTok Ads Manager: 1. Navigate to Assets → Audiences 2. Click "Create
          Audience" → "Customer File" 3. Upload your exported file 4. Map the columns
          to the appropriate identifier types (email, phone, IDFA, GAID) 5. Save your
          custom audience For detailed instructions, refer to the [TikTok Customer
          File Audience documentation](https://ads.tiktok.com/help/article?aid=9609).
        </Step>
      </Steps>
    </Expandable>
  </Tab>

  <Tab title="Web">
    ### Web Implementation Details

    The TikTok integration for web leverages the TikTok Pixel that is already installed on your site. Permutive does not add the TikTok Pixel - you must have it installed independently.

    When a user enters a cohort with TikTok activation enabled:

    1. Permutive fires a custom event via the TikTok Pixel with the event name `Permutive-{cohort_code}`
    2. If the user has a hashed email (`email_sha256`) in Permutive's identity framework, the pixel event is enriched with this identifier using TikTok's `identify` method
    3. TikTok receives the event and can match the user for audience building

    **How it works:**

    * Event names contain the cohort code because TikTok builds audiences based on event names, not event parameters
    * If multiple TikTok Pixels are installed on the page, Permutive will trigger events on each pixel
    * Enhanced matching with hashed email improves match rates and reduces reliance on cookies

    <Note>
      The TikTok Pixel must be present and initialized before Permutive attempts to
      fire events. Verify the pixel is loaded by checking for the global `ttq`
      object in your browser console.
    </Note>
  </Tab>

  <Tab title="iOS">
    ### iOS Implementation

    For iOS app audiences, use the User Export approach described in the "Alternative: User Export for Manual Upload" section.

    Export user lists with IDFA (Identifier for Advertisers) from Permutive and upload them to TikTok Ads Manager as a Customer File audience.
  </Tab>

  <Tab title="Android">
    ### Android Implementation

    For Android app audiences, use the User Export approach described in the "Alternative: User Export for Manual Upload" section.

    Export user lists with GAID (Google Advertising ID) from Permutive and upload them to TikTok Ads Manager as a Customer File audience.
  </Tab>
</Tabs>

## Data Types

With your TikTok integration setup, Permutive will send cohort activation events to TikTok via the TikTok Pixel:

<AccordionGroup>
  <Accordion title="Permutive Cohort Events">
    Custom events fired via the TikTok Pixel when a user enters an activated
    cohort. These events can be used to build custom audiences in TikTok Ads
    Manager.

    <ResponseField name="event_name" type="string">
      The event name follows the format `Permutive-{cohort_code}` where `       {cohort_code}` is the unique identifier for your Permutive cohort.
    </ResponseField>

    <ResponseField name="sha256_email" type="string (optional)">
      Hashed email address (SHA-256) passed to TikTok's identify method for
      enhanced user matching. Only included if available in Permutive's identity
      framework.
    </ResponseField>
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="TikTok Pixel not found">
    Verify that the TikTok Pixel is installed on your website by opening your
    browser console and running `ttq`. You should see the TikTok Analytics
    object. If not, you'll need to install the TikTok Pixel before using this
    integration. Contact your TikTok Account Manager or refer to the [TikTok
    Pixel installation guide](https://ads.tiktok.com/help/article?aid=10000357).
  </Accordion>

  <Accordion title="Events not appearing in TikTok Ads Manager">
    Check the following:

    * Verify that the TikTok integration is enabled for your workspace in Permutive
    * Confirm that cohorts are activated for TikTok in the Permutive Dashboard
    * Ensure users are entering the activated cohorts (check cohort membership in Permutive)
    * Allow up to 24 hours for events to appear in TikTok Ads Manager after initial setup
    * Navigate to Tools → Events in TikTok Ads Manager to verify event receipt
  </Accordion>

  <Accordion title="Low match rates for custom audiences">
    To improve match rates:

    * Ensure you're collecting hashed email addresses (SHA-256) via Permutive's identity framework
    * Verify that hashed emails are being passed to TikTok (check browser console for identify calls)
    * Consider using the User Export approach with multiple identifier types (email, mobile, IDFA, GAID)
    * Allow sufficient time for audience population - TikTok requires a minimum of 1,000 matched users for most custom audiences
  </Accordion>

  <Accordion title="Multiple TikTok Pixels on the same page">
    If you have multiple TikTok Pixels installed on your website, Permutive will trigger events on each pixel. This is expected behavior. Ensure that you're selecting the correct pixel when creating custom audiences in TikTok Ads Manager. To verify how many pixels are installed, check the `ttq` object in your browser console or review your site's tag management configuration.
  </Accordion>
</AccordionGroup>

## Changelog

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