# HYROS Installation: TikTok Ads

## IMPORTANT NOTES BEFORE STARTING

**Read these warnings first:**

1. **Using TripleWhale parameters?** You can go directly to Step 2 - skip the parameter installation.

2. **Updating ads resets learning phase** - TikTok now allows installing parameters to active ads, but this will reset the learning phase and require TikTok to re-approve your ads. The ROI gained from tracking outweighs this.

3. **Lead Generation Ads** - If you run Lead Generation Ads, see the special section below in addition to the standard setup.

---

## REQUIREMENTS - Collect Before Starting

| Item | Ask User |
|------|----------|
| TikTok Ads Manager Access | "Do you have admin access to your TikTok Ads Manager?" |
| Existing TripleWhale UTMs? | "Are you already using TripleWhale parameters? If yes, skip Step 1." |
| Lead Gen Ads? | "Are you running TikTok Lead Generation Ads (forms inside TikTok)?" |

---

## STEP 1: Add Tracking Parameters

**HYROS TikTok URL Parameter:**
```
ttc_id=__AID__&ttclid=__CLICKID__&h_ad_id=__CID__
```

**URL Formatting Rules:**
- If your URL has NO existing UTMs: Use `?ttc_id=__AID__&ttclid=__CLICKID__&h_ad_id=__CID__`
- If your URL ALREADY has UTMs: Use `&ttc_id=__AID__&ttclid=__CLICKID__&h_ad_id=__CID__`

**If automating:**
When creating or editing a TikTok ad (at the ad level), scroll down to the URL field. Add the HYROS parameter to the end of your destination URL. Publish the ad.

**If guiding user:**
1. "In your HYROS account, go to Tracking → Sources → Auto Source Parameters and copy the TikTok parameter."
2. "When creating a TikTok ad (at the ad level), scroll down to the URL field."
3. "Paste the parameter at the end of your URL (use '?' if no UTMs, or '&' if there are existing UTMs)."
4. "Publish the ad. (Note: You cannot edit the URL after publishing.)"

→ Confirm: "Are parameters added to your TikTok ads?"

---

## STEP 2: Integrate TikTok with HYROS

**If automating:**
In HYROS, navigate to Settings → Integrations → TikTok. Click "Add Account", name the integration, and complete the TikTok authorization. Select the ad account(s) to track.

**If guiding user:**
1. "In HYROS, go to Settings → Integrations."
2. "Find TikTok and click to configure."
3. "Click 'Add Account' and name the integration."
4. "Follow the prompts to log in to TikTok and authorize the connection."
5. "Select the ad account(s) you want to track."

→ Confirm: "Is TikTok connected in HYROS?"

---

## LEAD GENERATION ADS (Additional Setup)

If you use TikTok Lead Gen Ads (where leads are captured directly in TikTok forms), you need to enable the webhook:

**If automating:**
In HYROS, open the TikTok integration settings. Go to the Webhooks section. Toggle "Lead Ads Generation" to ON.

**If guiding user:**
1. "Log into your HYROS account."
2. "Go to the Settings section."
3. "Click on Integrations."
4. "Once inside the TikTok integration, click on Settings within that menu."
5. "A new menu will appear. Select Webhooks."
6. "Inside the Webhooks section, locate 'Lead Ads Generation'."
7. "Toggle Lead Ads Generation ON."

→ Confirm: "Is the Lead Ads webhook enabled?"

---

## TROUBLESHOOTING

### Manually Importing Ads
This is useful for awareness campaigns without a call-to-action button or when traffic isn't sent to your landing page.

Normally, click events are automatically imported into HYROS with costs. If there's no click event, you need to import the source manually to receive costs from those ads.

**Note:** This will NOT enable tracking view-through conversions or associating ads without CTAs with purchases. It WILL allow you to track the costs associated with the ads.

To configure: Go to your TikTok integration, click Configure, and click "Import" inside the "About" tab.

### Missing campaigns?
- Verify the TikTok integration is properly connected
- Check that ads have the correct tracking parameters
- Allow 24 hours for new campaigns to sync

---

## Source
Synced from: docsContent.ts (tiktokAdsIntegration)
Last synced: 2026-01-03