> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evomarketing.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Social platforms

> Social media platform integrations for content tracking

EVO Dialed integrates with social media platforms to track creator content and metrics.

## Supported platforms

| Platform  | Code | OAuth   | Scrape |
| --------- | ---- | ------- | ------ |
| TikTok    | `tt` | Yes     | Yes    |
| Instagram | `ig` | Partial | Yes    |
| YouTube   | `yt` | Yes     | Yes    |
| Facebook  | `fb` | No      | Yes    |

## Connection types

### OAuth

Direct API access via creator authorization:

* **Sync frequency:** Hourly
* **Cost:** API quota only
* **Data:** Complete metrics
* **Reliability:** High

### Scrape

Third-party scraping service:

* **Sync frequency:** Daily (10pm ET)
* **Cost:** Per-request billing
* **Data:** Public metrics only
* **Reliability:** Variable

<Note>
  OAuth catches viral posts faster (hourly vs daily). Encourage OAuth where possible.
</Note>

## TikTok integration

### OAuth flow

1. Creator taps "Connect TikTok"
2. Redirected to TikTok auth
3. Grants access permissions
4. Callback saves credentials
5. Hourly sync begins

### Scrape flow

1. Creator enters handle
2. Handle enters approval queue
3. Operator approves
4. Daily sync begins

### Data collected

* Profile info (handle, followers, bio)
* Video list with URLs
* View counts, likes, comments, shares
* Post timestamps

## Instagram integration

### Connection

Instagram primarily uses scraping:

* OAuth available for business accounts
* Most creators use scrape connection
* Handle entered manually

### Data collected

* Profile info
* Reels and posts
* View counts, likes, comments
* Post timestamps

### Limitations

* Stories not tracked
* Private accounts not supported
* Rate limits apply

## YouTube integration

### OAuth flow

1. Creator taps "Connect YouTube"
2. Google OAuth flow
3. Channel access granted
4. Hourly sync begins

### Data collected

* Channel info
* Video and Shorts list
* View counts, likes, comments
* Publish timestamps

## Facebook integration

### Scrape only

Facebook uses scraping exclusively:

* Reels tracked via scraping
* Per-post billing applies
* Limited to public content

### Data collected

* Reels and posts
* View counts, reactions
* Comment counts
* Post timestamps

## Account management

### CreatorSocial model

```ruby theme={null}
CreatorSocial.create!(
  user_id: creator.auth_user_id,
  platform: "tt",
  handle: "@creator",
  typ: "oauth",       # or "scrape"
  sync_status: "not_synced",
  approval_status: "pending"
)
```

### Brand linking

Socials must be linked to brands:

```ruby theme={null}
CreatorSocialBrand.create!(
  creator_social: social,
  brand: brand,
  user_id: creator.auth_user_id
)
```

<Warning>
  Without brand links, synced posts have no attribution target.
</Warning>

### Approval workflow

| Status     | Meaning                       |
| ---------- | ----------------------------- |
| `pending`  | Awaiting operator review      |
| `approved` | Active for syncing            |
| `rejected` | Not approved, reason provided |

## Sync process

### Daily scrape (10pm ET)

1. `Metrics::SyncJob` starts
2. Full roster processed (\~1,149 accounts)
3. Posts fetched from ScrapeCreators
4. `Metrics::Ingestor` processes posts
5. Submissions created/updated
6. Sync status updated

### OAuth sync (hourly)

1. `Metrics::OfficialSyncJob` starts
2. OAuth accounts only
3. Official API calls
4. Metrics updated

## Error handling

### Sync failures

| Status         | Meaning              |
| -------------- | -------------------- |
| `connected`    | Last sync successful |
| `sync_failed`  | Sync error occurred  |
| `needs_reauth` | OAuth token expired  |

### Retry logic

* Transient errors retry automatically
* Auth errors require creator action
* Persistent failures alert operators

## Backend implementation

**Key files:**

* `app/models/creator_social.rb` - Account model
* `app/models/creator_social_brand.rb` - Brand links
* `app/services/integrations/scrape_creators_client.rb` - Scraping
* `app/services/integrations/social_oauth_client.rb` - OAuth
* `app/jobs/metrics/sync_job.rb` - Daily sync
* `app/jobs/metrics/official_sync_job.rb` - OAuth sync