--- name: tiktok-shop-hourly-dashboard description: Fetch and compare real TikTok Shop GMV Max ad performance hour by hour, including orders, ad cost, gross revenue, ROI, cost per order, trends, and charts. Use when the user requests an hourly TikTok Ads dashboard, checks Kami, Hatomugi, Diem Quynh, or Redwin, asks why orders or ROI are falling, compares today with yesterday at the same time, or requests a scheduled hourly comparison. Use the connected TikTok Ads MCP; never invent metrics. --- # TikTok Shop Hourly Dashboard Produce concise, live, evidence-based TikTok GMV Max comparisons in Vietnamese. Default to four shops on the user's VN account. Use identical *completed* local hours for day-over-day comparisons, with charts and specific, measured findings. Never change ad settings without a separate explicit user request. ## Workflow 1. **Understand scope.** Infer the selected shop(s), metric(s), report cadence, and periods from the current request. Default shops: Diem Quynh Cosmetic, Kami Shop 36, REIHAKU HATOMUGI STORE, and Redwin Vietnam. Default comparison: today versus yesterday at matching hours. For "check Redwin" or "Kami vs Hato", restrict to those shops. 2. **Resolve local clock.** Determine the actual current date and time using the available clock/time tool, then confirm advertiser timezone (usually `Asia/Ho_Chi_Minh`). The default cutoff is the LAST COMPLETED HOUR: at 10:46, compare both days from 00:00 through 09:59, never include today's 10:00-10:46 in that fair comparison. Label an incomplete/live hour separately if requested; do not compare it with a full previous-day hour. If no hour has completed today, say so. 3. **Find and verify the advertiser and stores.** Use the connected TikTok Ads MCP. Follow `references/api-playbook.md`; consult `references/account-defaults.md` for lookup hints, not as substitutes for discovery. Check store ownership/authorization, currency and timezone. If access fails, report the blocker rather than fabricating data. 4. **Query genuine GMV Max data.** Call `gmv_max_report_get` for each store and each date with `dimensions=["campaign_id","stat_time_hour"]`, `metrics=["cost","gross_revenue","orders","roi","net_cost","cost_per_order"]`, `start_date=end_date=report_date`, and the single corresponding `store_ids` entry. Retrieve every page, and verify success. Include Product GMV Max and LIVE GMV Max campaigns where applicable; avoid duplicating campaign and product-level totals. Get current campaign status from `gmv_max_campaign_get` for context. Ordinary video-view ads require a *different* report endpoint and are excluded unless explicitly requested. 5. **Normalize strictly.** Ignore zero-valued future-hour placeholders and every row later than the common completed-hour cutoff. Sum `cost`, `gross_revenue`, and `orders` across all campaigns *within* each shop and hour. Do NOT sum or average ROI, cost per order, or campaign averages. Compute `revenue/cost`, `cost/orders`, and `revenue/orders` from sums; show `--` when a denominator is zero. Call this `ROI calculated from reported cost and gross revenue`; where TikTok's API supplies an authoritative aggregate ROI for the *same exact window*, show it separately and label it TikTok ROI. If rounded ROI differs from the TikTok ROI metric, do not silently mix them. 6. **Check data quality.** Confirm both periods represent exactly the same 00:00-HH:59 range; verify time zone, currency, number of campaigns, pagination, data-lag and any absent rows. Distinguish no data from confirmed zero. Never compare partial today against yesterday's whole day without an explicit "whole day" label. If two successive live queries differ slightly, state the as-of time and favor the latest reading. 7. **Present results.** Use the structure in `references/dashboard-layout.md`: a headline, compact day-over-day table by shop, *at least one directly displayed chart* when supported (orders by shop or hourly trend), percent deltas, then two to four grounded conclusions and actionable next checks. Keep charts legible on phones. If there are more than four shops, prioritize a table and one chart. For a single shop, give day-over-day hourly trend or compare completed-hour window first. 8. **Diagnose carefully.** Use cost, orders, ROI, and cost/order to distinguish *observable symptoms*: low delivery/spend, fewer orders despite similar spend, and lower revenue per order. These are NOT proof of weak CVR, ad fatigue, audience issues, or algorithm behavior. If seeking a root cause, inspect `campaign_gmv_max_info_get` (configured ROI target, budget, status), and store product/creative evidence where authorized. Report verified findings separately from hypotheses. See `references/api-playbook.md`. 9. **Respect authorization.** Reports are read-only. Never pause campaigns, raise budget, change ROI targets, or modify product listings unless the user *explicitly* authorizes the change. Do not store credentials, secret tokens, or exported user data in the skill package. ## Computation helper When deterministic verification is useful and code execution is available, pass the retrieved hourly report JSON to `scripts/aggregate_hourly.py` with current date, previous date, and cutoff hour. The script uses only Python's standard library and does not call any network API. It returns rounded summary statistics, per-hour data, and percentage changes. See `references/api-playbook.md` for input shape. Without code execution, apply precisely the aggregation rules above and cross-check totals yourself. ## Default presentation rules - Answer in natural Vietnamese, with clear numeric units. Show `USD` only if the advertiser currency was verified as USD; do not assume the shop product price currency is the ad-report currency. - Show orders as integers; USD with two decimals; ROI as `x`; deltas as signed percentages when a nonzero prior baseline exists. - Chart default: side-by-side grouped bars of completed-hour orders (today versus yesterday) for selected shops. Optionally show a per-hour line chart for any specific shop and a chart of calculated ROI when requested. - An alert can flag order decline of 30% or more with at least 10 prior-period orders, ROI decline of 25% or more with enough spend, or falling spend and orders together. Explicitly warn when samples are too small for strong conclusions. No arbitrary "problem detected" with only 1-2 orders. - Prefer precise wording: "Chi phi giam 58%, don giam 54%, chi phi/don gan nhu khong doi" over "video het hieu qua". Do not claim conversion rate changed unless click/visit data support that claim. - Include a brief verification timestamp: the report time and the compared hour window in the advertiser timezone. ## Automatic hourly delivery is separate The skill generates a report WHEN INVOKED; installing it does not start a timer. If the user asks for delivery every hour, create an hourly recurring task using a scheduling/automations feature **only after receiving that request** and if supported. The scheduled prompt should request this same skill and specify shops, completed-hour matched comparison, charts, and low-volume alerts. If no scheduler is available, explain the limitation. Never claim an automated report is active without confirmation from the scheduling tool. ## Examples - "Check 4 shop theo gio" -> report the four default shops today versus yesterday at matching completed hours, show an orders chart and concise ranking. - "Kami vs Hato, cung gio" -> compare those two shops only; separately flag spend slowing and revenue-per-order shifts. - "Redwin sao sang nay co 2 don?" -> retrieve prior-day identical hours and GMV Max campaign settings, distinguish confirmed comparisons from possible explanations. - "Moi gio gui bao cao 4 shop" -> create or request an hourly schedule separately; run this skill on each execution. ## References - [TikTok API query and validation playbook](references/api-playbook.md) - [Default advertiser and shop lookup hints](references/account-defaults.md) - [Phone-friendly report and chart layout](references/dashboard-layout.md)