TikTok Story Analytics

This tool provides privacy preserving analytics for TikTok Story viewers. It is designed for content creators, brand marketers, and social media analysts who want to understand who views TikTok Stories, when views occur, and how viewers engage. No individual identities are exposed; data is aggregated to enable audience planning and content optimization.
Core logic centers on secure data ingestion of required inputs (account_id, story_id, timeframe) and optional access token or data export. It retrieves analytics data from the official source or a supplied dataset, deduplicates viewer identifiers within the selected window, and computes key metrics such as total_views, unique_viewers, impressions, and average_watch_duration. Advanced features add demographic breakdowns (age, gender), geographic distribution, retention over time, and cross story comparisons. Outputs include summary metrics and optional breakdowns; exports to CSV or JSON for downstream reporting.
Error handling and localization address missing credentials, invalid IDs, timeframes outside retention, and API throttling with safe defaults and explicit caveats. The tool uses standard units (seconds for duration, counts for views) and supports ISO country codes for location data. Assumptions include authorized access to data sources; data is privacy preserving and aggregated. Exclusions include real-time spying, discovery of individual viewers, and any scraping beyond official APIs; outcomes are suitable for performance measurement, benchmarking, and content optimization.