Social platforms

​

Supported platforms

​

Connection types

​

OAuth

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

​

Scrape

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

​

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

• 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

• 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

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

CreatorSocialBrand.create!(
  creator_social: social,
  brand: brand,
  user_id: creator.auth_user_id
)

​

Approval workflow

​

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

​

Retry logic

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

​

Backend implementation

• 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