Metryki wideo TikTok przez API: wyświetlenia, czas oglądania i ukończenie
TikTok API for Business zwraca łączne metryki każdego posta od jego publikacji z GET /business/video/list/, wskazane po nazwie w fields: video_views, reach, likes, comments, shares i favorites, total_time_watched i average_time_watched w sekundach, full_video_watched_rate, video_view_retention, impression_sources oraz rozkłady widzów, takie jak audience_countries. Większość liczników dociera z opóźnieniem 24 do 48 godzin i przestaje się aktualizować 365 dni po publikacji.
easyCoexistence odczytuje metryki filmu TikTok przez get_social_insights z poziomu Claude, ChatGPT lub własnego kodu: wymieniasz pola, których chcesz, na przykład video_views, reach lub full_video_watched_rate, i podajesz item_id filmu.
Zakres potrzebny do czasu oglądania, ukończenia, retencji, źródeł ruchu i rozkładów widzów; podstawowe liczniki wymagają video.list.
Okres bezczynności, po którym przy danym filmie mogą brakować zasięg, czas oglądania, źródła ruchu i audience_countries.
Większość wpisów na listach audience_countries i audience_cities danego filmu.
Typowe opóźnienie dla video_views, likes, reach, czasu oglądania i źródeł ruchu, w czasie UTC.
Jakie metryki ma film?
GET /business/video/list/ zwraca je dla każdego posta wskazanego w fields, zsumowane za całe życie posta, a nie za 60-dniowe okno metryk konta. Liczniki, takie jak wyświetlenia i polubienia, wymagają zakresu video.list w tokenie, a dane o oglądaniu, ukończeniu i retencji wymagają video.insights:
Jak je zamówić?
Wymień je w fields, w tablicy JSON, która musi zawierać item_id, gdy wymienia więcej niż jedno pole, i wybierz posty za pomocą filters.video_ids. Bez tego filtra endpoint przechodzi przez posty konta, po 20 naraz:
curl -G 'https://business-api.tiktok.com/open_api/v1.3/business/video/list/' \
-H 'Access-Token: <ACCESS_TOKEN>' \
--data-urlencode 'business_id=<OPEN_ID>' \
--data-urlencode 'fields=["item_id","video_views","reach","video_duration","total_time_watched","average_time_watched","full_video_watched_rate","impression_sources","audience_countries"]' \
--data-urlencode 'filters={"video_ids":["<ITEM_ID>"]}'Jak wygląda odpowiedź?
Tablica videos z jednym obiektem na post i żądanymi polami, plus cursor i has_more do stronicowania. Przykład TikToka, skrócony, pokazuje jednostki: czasy oglądania w sekundach z trzema miejscami po przecinku, a full_video_watched_rate jako ułamek dziesiętny, tutaj 0.0237:
{
"code": 0,
"message": "OK",
"request_id": "2021080307532501024502410704A7306F",
"data": {
"videos": [
{
"item_id": "6990565363377392901",
"video_views": 1231,
"reach": 154,
"likes": 10,
"comments": 2,
"shares": 0,
"video_duration": 20.0,
"total_time_watched": 695.942,
"average_time_watched": 4.118,
"full_video_watched_rate": 0.0237,
"impression_sources": [
{ "impression_source": "For You", "percentage": 0.8983 },
{ "impression_source": "Personal Profile", "percentage": 0.0904 },
{ "impression_source": "Follow", "percentage": 0.0113 }
],
"audience_countries": [
{ "country": "US", "percentage": 0.7574 },
{ "country": "GB", "percentage": 0.1775 }
]
}
],
"cursor": 0,
"has_more": false
}
}Co znaczą źródła ruchu?
impression_sources klasyfikuje, skąd widzowie odkryli post, od największego udziału do najmniejszego; każdy wpis to impression_source z procentem. TikTok dokumentuje te wartości:
- For You: kanał For You.
- Follow: kanał Follow.
- Sound: strony dźwięku.
- Personal Profile: strony profilu.
- Search: strony wyszukiwania.
- Direct Message: wiadomości bezpośrednie, gdy TikTok Studio pokazuje te dane dla konta.
- Others: wszystko inne.
Jakie są rozkłady widzów?
Cztery, wszystkie opisują osoby, które obejrzały dany post, a nie obserwujących konto, i wszystkie wymagają video.insights:
audience_genders: udział widzów według płci: Female, Male lub Other.audience_countries: do 10 krajów lub regionów, w kodach ISO 3166-1 alpha-2.audience_cities: do 10 miast, zapisanych jak US Cincinnati.audience_types:NEW_VIEWERiRETURN_VIEWERorazFOLLOWER_PERCENTwobecNON_FOLLOWER_PERCENT.
Które metryki zależą od typu konta?
Kilka kliknięć i wizyt w profilu pochodzi z TikTok Business Analytics i wymaga więcej niż konta osobistego. profile_views, czyli wizyty w profilu wywołane przez post, wymaga konta z Advanced Access lub Verified Business Account. website_clicks, phone_number_clicks, lead_submissions, app_download_clicks, email_clicks i address_clicks wymagają Verified Business Account.
Dlaczego metryka może brakować lub się spóźniać?
Ponieważ TikTok liczy większość z nich offline i wyłącznie z TikTok Analytics. Liczniki i metryki oglądania zwykle opóźniają się o 24 do 48 godzin, podczas gdy item_id, opis i linki są w czasie rzeczywistym. Zasięg, czas oglądania, źródła ruchu i audience_countries mogą brakować przy filmie, którego nikt nie obejrzał, nie polubił, nie skomentował ani nie udostępnił przez 7 dni; wskazówka TikToka brzmi: zaangażuj się w ten film i ponów zapytanie po 24 do 48 godzinach. Dane przestają się aktualizować 365 dni po publikacji, a posty odfiltrowane za naruszenia, na przykład praw autorskich do muzyki, nie są zwracane.
Jak easyCoexistence odczytuje metryki filmu?
Za pomocą get_social_insights: podajesz item_id filmu jako object_id i nazwy pól jako metrics, a narzędzie zwraca pola tego posta, szukając wśród 20 najnowszych postów konta. Dla starszego posta Twój własny kod wywołuje business/video/list/ z fields i filters.video_ids jako parametrami, używając tokena z get_social_credentials.
get_social_insights {
"account_id": "<ACCOUNT_ID>",
"object_id": "<ITEM_ID>",
"metrics": ["video_views", "reach", "average_time_watched", "full_video_watched_rate", "impression_sources"]
}Typowe błędy
- Zakładanie jednej skali dla każdego procentu. Przykłady TikToka podają impression_sources jako ułamki sumujące się do 1, podczas gdy jego przykład audience_cities pokazuje wartości takie jak 17.4921.
- Żądanie kilku pól bez item_id. Dokumentacja TikToka ostrzega, że takie żądanie może się nie udać.
- Oczekiwanie zasięgu dla starego, cichego filmu. TikTok może pozostawić zasięg, czas oglądania i źródła ruchu puste po 7 dniach bez wyświetleń, polubień, komentarzy i udostępnień.
- Porównywanie metryk posta z dziennymi metrykami konta. Dane posta obejmują całe jego życie, a metryki konta przychodzą dziennie przez maksymalnie 60 dni.
Dla starszych postów get_social_credentials daje własnemu kodowi token konta. US$ 9 do US$ 0.75 za połączenie miesięcznie, z każdym kolejnym połączeniem taniej, z pierwszymi 3 dniami bezpłatnie.
Najczęściej zadawane pytania
Czy TikTok API zwraca czas oglądania dla każdego filmu?
Tak. total_time_watched i average_time_watched przychodzą w sekundach z /business/video/list/, dla tokenów z zakresem video.insights.
Jak przez API pobrać wskaźnik ukończenia filmu TikTok?
Zażądaj full_video_watched_rate w fields na /business/video/list/. TikTok definiuje go jako procent widzów, którzy obejrzeli film do końca.
Dlaczego zasięg i czas oglądania są puste dla mojego filmu TikTok?
TikTok może je pominąć dla filmu bez wyświetleń, polubień, komentarzy i udostępnień w ciągu ostatnich 7 dni, a świeże dane opóźniają się o 24 do 48 godzin.
Czy API może zwrócić metryki jednego konkretnego filmu TikTok?
Tak. Przekaż jego ID w filters.video_ids, a w fields podaj item_id i metryki, które chcesz.
Czytaj dalej
Połącz pierwszy kanał w dwie minuty.
Bez czekania na weryfikację przez platformy. Połącz WhatsApp, Instagram, TikTok lub inny kanał, a potem poproś swoją AI o opublikowanie posta, odpowiedź lub raport i zobacz, jak działa.
- 3 dni za darmo
- Rezygnacja w każdej chwili
- Tylko oficjalne API
- Monitorowanie 24/7
Zweryfikowano w