> ## Documentation Index > Fetch the complete documentation index at: https://docs.datalyr.com/llms.txt > Use this file to discover all available pages before exploring further. # 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):** ```javascript theme={null} // TikTok Pixel fires client-side ttq.track('CompletePayment', { value: 79.99, currency: 'USD' }); ``` **Events API (Server-Side):** ```javascript theme={null} // 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:** ```javascript theme={null} // 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:** ```javascript theme={null} // Original (NEVER sent in plain text) email: "user@example.com" phone: "+14155551234" // 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: user@example.com Order: $79.99 DATALYR links: 1. Desktop visitor → user@example.com 2. Mobile visitor → user@example.com 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: ```javascript theme={null} // 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: ```javascript theme={null} { "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:** ```javascript theme={null} // Before Email: "user@example.com" // After (sent to TikTok) email: "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514" ``` ## Next Steps Send conversions to Facebook Track Google Ads performance Send conversions to OpenAI's CAPI Configure conversion mapping View attribution paths ## Need Help? Questions about TikTok Ads integration? Check our [troubleshooting guide](/troubleshooting/integration-errors) or contact support.