Les campagnes de hashtag TikTok nécessitent une surveillance continue pour mesurer la portée, l'engagement et la participation des créateurs. La vérification manuelle est impraticable dès qu'une campagne implique des dizaines de créateurs. Ce tutoriel construit un pipeline automatisé de surveillance de hashtag utilisant l'API Scavio TikTok qui suit le nombre total de vues, les nouvelles soumissions de vidéos, les métriques d'engagement et le contenu le plus performant. Chaque appel API coûte 1 crédit (0,005 $), et une vérification complète de campagne utilise 2 à 3 crédits.
Prérequis
- Python 3.9+ installé
- bibliothèque requests installée
- Une clé API Scavio depuis scavio.dev
- Un hashtag de campagne à surveiller
Parcours
Étape 1: Obtenir les statistiques générales du hashtag
Récupérez les statistiques globales de votre hashtag de campagne : nombre total de vues, nombre total de vidéos et l'ID du hashtag. Cela vous donne les métriques de campagne de premier niveau.
Python
import requests, os
API_KEY = os.environ['SCAVIO_API_KEY']
TIKTOK_URL = 'https://api.scavio.dev/api/v1/tiktok'
def get_hashtag_stats(hashtag: str) -> dict:
resp = requests.post(f'{TIKTOK_URL}/hashtag',
headers={'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json'},
json={'hashtag': hashtag})
resp.raise_for_status()
data = resp.json().get('data', {})
return {
'hashtag': hashtag,
'id': data.get('id', ''),
'view_count': data.get('stats', {}).get('view_count', 0),
'video_count': data.get('stats', {}).get('video_count', 0)
}
stats = get_hashtag_stats('yourcampaign')
print(f'#{stats["hashtag"]}: {stats["view_count"]:,} views, {stats["video_count"]:,} videos')Étape 2: Récupérer les vidéos récentes du hashtag
Obtenez les dernières vidéos publiées avec votre hashtag de campagne. Cela montre l'activité en temps réel de la campagne et la participation des créateurs.
Python
def get_hashtag_videos(hashtag: str, count: int = 30) -> list:
resp = requests.post(f'{TIKTOK_URL}/hashtag/posts',
headers={'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json'},
json={'hashtag': hashtag, 'count': count, 'cursor': 0})
resp.raise_for_status()
videos = resp.json().get('data', {}).get('videos', [])
return [{
'id': v.get('id', ''),
'author': v.get('author', {}).get('uniqueId', ''),
'author_followers': v.get('author', {}).get('stats', {}).get('followerCount', 0),
'desc': v.get('desc', ''),
'plays': v.get('stats', {}).get('playCount', 0),
'likes': v.get('stats', {}).get('diggCount', 0),
'comments': v.get('stats', {}).get('commentCount', 0),
'shares': v.get('stats', {}).get('shareCount', 0),
'create_time': v.get('createTime', 0)
} for v in videos]
videos = get_hashtag_videos('yourcampaign')
print(f'Found {len(videos)} recent videos')
for v in videos[:3]:
print(f' @{v["author"]}: {v["plays"]:,} plays, {v["likes"]:,} likes')Étape 3: Calculer les métriques d'engagement de la campagne
Calculez les métriques d'engagement agrégées sur toutes les vidéos de la campagne : portée totale, taux d'engagement moyen et distribution de l'engagement.
Python
import statistics
def campaign_metrics(videos: list) -> dict:
if not videos:
return {'total_reach': 0, 'avg_engagement': 0}
total_plays = sum(v['plays'] for v in videos)
total_likes = sum(v['likes'] for v in videos)
total_comments = sum(v['comments'] for v in videos)
total_shares = sum(v['shares'] for v in videos)
eng_rates = [
(v['likes'] + v['comments'] + v['shares']) / max(v['plays'], 1) * 100
for v in videos
]
unique_creators = len(set(v['author'] for v in videos))
return {
'total_videos': len(videos),
'unique_creators': unique_creators,
'total_reach': total_plays,
'total_engagement': total_likes + total_comments + total_shares,
'avg_engagement_rate': round(statistics.mean(eng_rates), 2),
'median_engagement_rate': round(statistics.median(eng_rates), 2),
'total_likes': total_likes,
'total_comments': total_comments,
'total_shares': total_shares
}
metrics = campaign_metrics(videos)
for k, v in metrics.items():
print(f'{k}: {v:,}' if isinstance(v, int) else f'{k}: {v}')Étape 4: Identifier le contenu et les créateurs les plus performants
Classez les vidéos et les créateurs par performance pour identifier votre meilleur contenu et les participants les plus précieux de la campagne.
Python
def top_performers(videos: list) -> dict:
# Top videos by engagement
by_engagement = sorted(videos,
key=lambda v: v['likes'] + v['comments'] + v['shares'], reverse=True)
# Top creators by total plays across their videos
creator_plays = {}
for v in videos:
creator_plays.setdefault(v['author'], 0)
creator_plays[v['author']] += v['plays']
top_creators = sorted(creator_plays.items(), key=lambda x: x[1], reverse=True)
return {
'top_videos': [{
'author': v['author'],
'plays': v['plays'],
'likes': v['likes'],
'desc': v['desc'][:60]
} for v in by_engagement[:5]],
'top_creators': [{
'username': c[0],
'total_plays': c[1]
} for c in top_creators[:5]]
}
performers = top_performers(videos)
print('Top videos:')
for v in performers['top_videos']:
print(f' @{v["author"]}: {v["plays"]:,} plays, {v["likes"]:,} likes')
print('Top creators:')
for c in performers['top_creators']:
print(f' @{c["username"]}: {c["total_plays"]:,} total plays')Étape 5: Mettre en place une surveillance quotidienne avec suivi historique
Enregistrez des instantanés quotidiens pour suivre la croissance de la campagne dans le temps. Comparez les métriques d'aujourd'hui avec celles d'hier pour voir les progrès quotidiens.
Python
import json
from datetime import date
def daily_campaign_report(hashtag: str) -> dict:
stats = get_hashtag_stats(hashtag)
videos = get_hashtag_videos(hashtag, count=30)
metrics = campaign_metrics(videos)
performers = top_performers(videos)
report = {
'date': date.today().isoformat(),
'hashtag': hashtag,
'overview': stats,
'metrics': metrics,
'top_performers': performers,
'credits_used': 2
}
# Save and compare with previous
history_file = f'campaign_{hashtag}_history.json'
try:
with open(history_file) as f:
history = json.load(f)
except FileNotFoundError:
history = []
history.append(report)
with open(history_file, 'w') as f:
json.dump(history, f, indent=2)
if len(history) > 1:
prev = history[-2]
view_delta = stats['view_count'] - prev['overview']['view_count']
print(f'Daily growth: +{view_delta:,} views')
print(f'Campaign #{hashtag}: {stats["view_count"]:,} total views, '
f'{metrics["unique_creators"]} creators, {metrics["avg_engagement_rate"]}% avg engagement')
return report
# daily_campaign_report('yourcampaign')Exemple Python
Python
import os, requests, statistics
API_KEY = os.environ['SCAVIO_API_KEY']
TT = 'https://api.scavio.dev/api/v1/tiktok'
def tiktok(endpoint, body):
return requests.post(f'{TT}/{endpoint}',
headers={'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'},
json=body).json()
def monitor_hashtag(hashtag):
stats = tiktok('hashtag', {'hashtag': hashtag}).get('data', {})
videos = tiktok('hashtag/posts', {'hashtag': hashtag, 'count': 30, 'cursor': 0})
vids = videos.get('data', {}).get('videos', [])
total_plays = sum(v.get('stats', {}).get('playCount', 0) for v in vids)
creators = len(set(v.get('author', {}).get('uniqueId', '') for v in vids))
print(f'#{hashtag}: {stats.get("stats", {}).get("view_count", 0):,} views')
print(f' Recent: {len(vids)} videos, {creators} creators, {total_plays:,} plays')
print(f' Cost: 2 credits ($0.01)')
monitor_hashtag('yourcampaign')Exemple JavaScript
JavaScript
const API_KEY = process.env.SCAVIO_API_KEY;
const TT = 'https://api.scavio.dev/api/v1/tiktok';
async function tiktokApi(endpoint, body) {
const resp = await fetch(`${TT}/${endpoint}`, {
method: 'POST',
headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify(body)
});
return resp.json();
}
async function monitorHashtag(hashtag) {
const stats = await tiktokApi('hashtag', { hashtag });
const videos = await tiktokApi('hashtag/posts', { hashtag, count: 30, cursor: 0 });
const vids = videos.data?.videos || [];
const plays = vids.reduce((s, v) => s + (v.stats?.playCount || 0), 0);
const creators = new Set(vids.map(v => v.author?.uniqueId)).size;
console.log(`#${hashtag}: ${vids.length} videos, ${creators} creators, ${plays.toLocaleString()} plays`);
}
monitorHashtag('yourcampaign').catch(console.error);Sortie attendue
JSON
#yourcampaign: 2,450,000 views, 1,234 videos
Found 30 recent videos
@creator1: 145,000 plays, 12,300 likes
@creator2: 89,000 plays, 7,800 likes
@creator3: 67,000 plays, 5,400 likes
total_videos: 30
unique_creators: 22
total_reach: 1,234,000
avg_engagement_rate: 8.45
Daily growth: +45,000 views
Cost: 2 credits ($0.01)