TikTok UGC Tracking for Campaign ROI Measurement

import requests
from datetime import date

def track_campaign_hashtag(hashtag: str) -> dict:
    """Track UGC campaign performance via hashtag."""
    resp = requests.post(
        "https://api.scavio.dev/api/v1/tiktok/search/videos",
        headers={"Authorization": "Bearer YOUR_KEY"},
        json={
            "query": f"#{hashtag}",
            "count": 30,
            "sort_type": 0  # By date (most recent)
        }
    )
    data = resp.json()
    videos = data.get("data", {}).get("videos", [])

    total_views = 0
    total_likes = 0
    total_comments = 0
    total_shares = 0
    creators = set()

    for v in videos:
        stats = v.get("stats", {})
        total_views += stats.get("playCount", 0)
        total_likes += stats.get("diggCount", 0)
        total_comments += stats.get("commentCount", 0)
        total_shares += stats.get("shareCount", 0)
        creators.add(v.get("author", {}).get("uniqueId", "unknown"))

    total_engagements = total_likes + total_comments + total_shares
    return {
        "hashtag": hashtag,
        "date": str(date.today()),
        "videos_found": len(videos),
        "unique_creators": len(creators),
        "total_views": total_views,
        "total_engagements": total_engagements,
        "avg_engagement_rate": round(
            total_engagements / total_views * 100, 2
        ) if total_views > 0 else 0
    }

# Track your campaign
report = track_campaign_hashtag("YourBrandCampaign")
print(f"Videos: {report['videos_found']}")
print(f"Views: {report['total_views']:,}")
print(f"Engagement rate: {report['avg_engagement_rate']}%")

// Calculate ROI per creator in your campaign
async function creatorRoiBreakdown(creators, campaignHashtag, paymentPerCreator) {
  const breakdown = [];

  for (const creator of creators) {
    // Get creator's campaign posts
    const resp = await fetch(
      "https://api.scavio.dev/api/v1/tiktok/user/posts",
      {
        method: "POST",
        headers: {
          "Authorization": "Bearer " + process.env.SCAVIO_KEY,
          "Content-Type": "application/json"
        },
        body: JSON.stringify({ username: creator, count: 20 })
      }
    );

    const data = await resp.json();
    const posts = data.data?.videos || [];

    // Filter for campaign posts
    const campaignPosts = posts.filter(p =>
      p.desc?.toLowerCase().includes(campaignHashtag.toLowerCase())
    );

    let totalEngagements = 0;
    for (const p of campaignPosts) {
      const s = p.stats || {};
      totalEngagements += (s.diggCount || 0) + (s.commentCount || 0) + (s.shareCount || 0);
    }

    const costPerEngagement = totalEngagements > 0
      ? (paymentPerCreator / totalEngagements).toFixed(3)
      : "N/A";

    breakdown.push({
      creator,
      campaignPosts: campaignPosts.length,
      totalEngagements,
      costPerEngagement,
      payment: paymentPerCreator
    });
  }

  return breakdown.sort((a, b) => b.totalEngagements - a.totalEngagements);
}

Metric                | Formula
Cost per view (CPV)   | Total spend / Total views
Cost per engagement   | Total spend / (Likes + Comments + Shares)
Earned media value    | Total views x $0.01 (industry benchmark)
ROI                   | (Earned media value - Total spend) / Total spend