TikTok Ads

Send conversions to TikTok with Events API for improved attribution and optimization

The TikTok Ads integration sends conversions to TikTok using the Events API for server-side tracking, improving attribution accuracy and campaign optimization despite browser tracking limitations.

What Gets Synced

Ad Performance Data (From TikTok):

• Campaign, ad group, ad stats
• Spend, impressions, clicks
• CPC, CTR, conversion metrics
• ROAS data

Conversion Data (To TikTok):

• Purchase events with revenue
• Add to cart, checkout events
• Registration/signup events
• Lead form submissions
• Custom events you configure

How It Works

Conversion Flow

1. User Clicks TikTok Ad

User clicks TikTok ad
TikTok appends ttclid to URL
URL: https://yoursite.com/?ttclid=xyz123...

2. DATALYR Captures Click ID

DATALYR tracking script captures:
- ttclid: xyz123...
- _ttp cookie (TikTok Pixel browser ID)
Stores in visitor profile: anon_abc123

3. User Converts

User completes purchase: $79.99
DATALYR tracks conversion event

4. Conversion Sent to TikTok Events API

DATALYR sends server-side event:
- Event: CompletePayment
- Value: $79.99
- ttclid: xyz123 (from Day 1)
- Enhanced matching: email, phone (hashed)
- Event ID for deduplication

5. TikTok Attributes Conversion

TikTok receives conversion
Matches ttclid to original ad click
Attributes $79.99 to TikTok campaign
Updates campaign optimization

Result: Purchase correctly attributed to TikTok ad for campaign optimization.

Setup

1. Connect TikTok Ads Account

1. Navigate to Settings → Sources in DATALYR
2. Click “Connect” next to TikTok Ads
3. Log in to TikTok Ads Manager account
4. Select advertiser account
5. Grant permissions:
   • Read ad performance data
   • Send conversion events
   • Access TikTok Pixel
6. Click “Authorize”

2. Select Primary Advertiser Account

After connecting:

1. DATALYR shows all accessible advertiser accounts
2. Select your primary advertiser ID
3. Select TikTok Pixel to use for Events API
4. Click “Save”

3. Configure Events

1. Go to Settings → Conversion Rules in DATALYR

2. Map your events to TikTok standard events:

   • purchase → CompletePayment
   • add_to_cart → AddToCart
   • begin_checkout → InitiateCheckout
   • signup → CompleteRegistration
   • lead → SubmitForm

3. Set conversion values:

   • Use order total for purchases
   • Fixed value for leads/signups

4. Verify Integration

Test Conversion:

1. Click TikTok ad (use test campaign if available)
2. Complete conversion on your site
3. Go to TikTok Ads Manager → Events
4. Check “Event History” tab
5. Verify conversion appears with “API” source

TikTok Events API

Why Events API Matters

Browser Pixel Limitations:

• iOS tracking restrictions
• Ad blockers
• Cookie consent requirements
• Browser privacy features

Events API Benefits:

• Server-side tracking (no browser required)
• Works reliably where browser pixels are limited on iOS 14+
• Immune to ad blockers
• Better attribution accuracy
• Improved campaign optimization

How Events API Works

TikTok Pixel (Browser):

// TikTok Pixel fires client-side
ttq.track('CompletePayment', {
  value: 79.99,
  currency: 'USD'
});

Events API (Server-Side):

// DATALYR sends to TikTok Events API
POST https://business-api.tiktok.com/open_api/v1.3/event/track/
{
  "event_source": "web",
  "event_source_id": "PIXEL_ID",
  "data": [{
    "event": "CompletePayment",
    "event_time": 1727634645,
    "event_id": "evt_123",
    "page": {
      "url": "https://example.com/checkout"
    },
    "user": {
      "email": "hashed_email",
      "phone_number": "hashed_phone",
      "ttp": "_ttp_cookie",
      "ttclid": "xyz123"
    },
    "properties": {
      "value": 79.99,
      "currency": "USD"
    }
  }]
}

Deduplication

DATALYR deduplicates between browser pixel and Events API:

Event ID Matching:

// Browser Pixel
ttq.track('CompletePayment', {...}, {event_id: 'evt_123'})

// Events API
event_id: 'evt_123'

Result: TikTok counts as ONE conversion (not two)

Enhanced Matching

DATALYR sends hashed customer data to improve match rates:

Customer Data Sent

Always Hashed (SHA-256):

• Email address
• Phone number

Example:

// Original (NEVER sent in plain text)
email: "[e-mail]"
phone: "[phone]"

// Hashed before sending
email: "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514"
phone_number: "8c2b7e9e4e7e3f7a5d0c5f6e4e7e3f7a5d0c5f6e4e7e3f7a5d0c5f6e4e7e3f7a"

TikTok IDs

_ttp (TikTok Pixel Cookie):

• First-party cookie set by TikTok Pixel
• Identifies browser/device
• Format: {uuid}

ttclid (TikTok Click ID):

• Appended to URL by TikTok ads
• Unique identifier for each ad click
• Used for attribution

Attribution

Cross-Device Attribution

DATALYR attributes conversions across devices:

Example:

Mobile (Day 1):

User clicks TikTok ad on mobile
ttclid captured: xyz123
Visitor ID: anon_mobile_789

Desktop (Day 3):

User purchases on desktop
Email: [e-mail]
Order: $79.99

DATALYR links:
1. Desktop visitor → [e-mail]
2. Mobile visitor → [e-mail]
3. Finds ttclid from mobile click
4. Sends conversion with original ttclid

Result: Desktop purchase attributed to mobile TikTok ad.

Attribution Windows

TikTok Default Windows:

• 28-day click attribution
• 1-day view attribution

DATALYR Settings:

• 30-day attribution window (default)
• Configurable per workspace

Conversions outside the window are not sent to TikTok.

Event Mapping

Standard Events

Map your events to TikTok standard events:

Your Event	TikTok Event	Use Case
purchase	CompletePayment	Purchase completed
add_to_cart	AddToCart	Add item to cart
begin_checkout	InitiateCheckout	Start checkout
signup	CompleteRegistration	User registration
lead	SubmitForm	Lead form submission
view_content	ViewContent	Product page view
search	Search	Site search

Custom Events

Send custom events for specific business needs:

// Track subscription start
datalyr.track('subscription_started', {
  plan: 'pro',
  value: 29.99
});

// Maps to TikTok custom event
Event: subscription_started
Properties: {plan: 'pro', value: 29.99}

Product Data

Contents Array

Send product details for better campaign optimization:

{
  "contents": [{
    "content_id": "SKU123",
    "content_name": "Wireless Headphones",
    "content_category": "Electronics",
    "quantity": 2,
    "price": 49.99
  }],
  "value": 99.98,
  "currency": "USD"
}

Benefits:

• Product-level insights
• Dynamic product ads optimization
• Better ROAS tracking

Advanced Features

Event Source

DATALYR automatically sets the correct event_source:

web: Web-based conversions (default)

User converts on website
event_source: "web"

app: Mobile app conversions

User converts in mobile app
event_source: "app"

Test Events

Test conversions before going live:

1. Enable test mode in DATALYR
2. Create test conversion
3. Check TikTok Events Manager → Test Events
4. Verify data is correct
5. Disable test mode for production

Troubleshooting

Conversions Not Appearing

Check:

1. Integration is connected and active
2. TikTok Pixel ID is correct
3. Event has ttclid parameter
4. Within attribution window (28 days)
5. Check TikTok Events Manager for errors

Common Issues:

• Missing ttclid: User didn’t click TikTok ad
• Wrong advertiser ID: Verify account selected
• Duplicate event IDs: Check deduplication

Low Match Rate

Improve matching by:

1. Send email with every conversion
2. Include phone number (E.164 format)
3. Capture _ttp cookie from TikTok Pixel
4. Ensure ttclid is preserved in URLs

Check:

TikTok Events Manager → Data Sources → Your Pixel → Event Quality

Target: 60%+ match rate

Attribution Discrepancies

DATALYR vs TikTok Numbers:

Common reasons for differences:

• Attribution windows differ (DATALYR: 30d, TikTok: 28d)
• View-through attribution (TikTok counts, DATALYR doesn’t by default)
• Conversion time differences

Best Practice: Use DATALYR for source of truth, TikTok for optimization signals.

Campaign Optimization

How Conversions Improve Performance

TikTok uses conversion data to optimize:

• Campaign Budget Optimization (CBO): Distribute budget to best ad sets
• Lowest Cost bidding: Get most conversions in budget
• Cost Cap: Get conversions below target CPA
• Value Optimization: Maximize revenue

More conversion data = Better optimization

Best Practices

1. Send all conversions: Including micro-conversions (add to cart, etc.)
2. Accurate values: Use actual order values for purchases
3. Timely uploads: DATALYR sends immediately
4. 50+ events/week: Minimum for campaign learning phase

Data Privacy

Customer Data:

• All emails and phones are SHA-256 hashed
• No plaintext PII sent to TikTok
• GDPR and CCPA compliant
• Opt-out respected

Hashing Example:

// Before
Email: "[e-mail]"

// After (sent to TikTok)
email: "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514"

Next Steps

Meta Ads

Send conversions to Facebook

Google Ads

Track Google Ads performance

OpenAI Ads

Send conversions to OpenAI’s CAPI

Conversion Rules

Configure conversion mapping

Customer Journeys

View attribution paths

Need Help?

Questions about TikTok Ads integration? Check our troubleshooting guide or contact support.