개요 TikTok Business API — Discovery
이 페이지는 TikTok Business API의 Discovery 엔드포인트를 통해 데이터를 수집합니다. 광고주 계정(Advertiser)과 비즈니스 센터(Business Center)의 인증 정보를 사용하며, 모든 요청은 서버(PHP)에서 처리됩니다.
인증 인증 흐름
🔑
config/tiktok_config.php
access_token, advertiser_id, bc_id 보관
→
📡
trending_hashtag_provider.php
인증 정보를 로드하여 API 요청 헤더에 Access-Token 포함
→
🌐
TikTok Business API
cURL GET 요청 (서버→서버)
API 사용 엔드포인트 (3개)
① 인기 해시태그 목록 조회 — 페이지 진입 시 또는 [조회] 버튼 클릭 시 호출
| 파라미터 | 설명 | 기본값 |
|---|
advertiser_id | 광고주 ID (필수) | config 설정값 |
discovery_type | 탐색 유형 | HASHTAG |
country_code | 국가 코드 | KR (상단 필터) |
date_range | 조회 기간 | 상단 필터 값 |
category_name | 업종 카테고리 (선택) | ALL |
응답 필드: hashtag_id, hashtag_name, video_views, publish_cnt, trend 등 (최대 200개)
② 해시태그 상세 조회 — 특정 해시태그의 세부 트렌드 데이터 조회
| 파라미터 | 설명 | 기본값 |
|---|
bc_id | 비즈니스 센터 ID (필수) | config 설정값 |
asset_id | 광고주 ID (필수) | config 설정값 |
hashtag_id / hashtag_name | 조회 대상 (택 1) | 클릭된 해시태그 |
country_code | 국가 코드 | KR |
③ 해시태그 인기 비디오 조회 — 해시태그 클릭 시 우측 패널에 비디오 로드
| 파라미터 | 설명 | 기본값 |
|---|
bc_id | 비즈니스 센터 ID (필수) | config 설정값 |
advertiser_id | 광고주 ID (필수) | config 설정값 |
hashtag_ids / hashtag_name | 해시태그 식별자 | 클릭된 해시태그 |
country_code | 국가 코드 | 상단 필터 값 |
date_range | 조회 기간 | 상단 필터 값 |
discovery_type | 탐색 유형 | HASHTAG |
응답 필드: video_id, embed_url, share_url, like_count, comment_count, share_count, view_count
흐름 전체 데이터 흐름
프론트엔드 (브라우저)
사용자가 필터(국가/기간/업종)를 설정하고
[조회] 클릭 또는 해시태그 클릭
▼ fetch() — GET 요청 + 쿼리스트링
Provider (PHP 서버)
action 파라미터로 분기
trending → fetchTrendingList()
hashtag_video → fetchHashtagVideo()
detail → fetchHashtagDetail()
rate_status → Rate Limit 잔여 현황 반환
▼ Rate Limiter 적용
DiscoveryRateLimiter
파일 기반 슬라이딩 윈도우 (60초 단위)
제한 초과 시 대기 또는 429 반환
429 응답 시 지수 백오프 재시도 (최대 3회)
▼ cURL GET + Access-Token 헤더
TikTok Business API 서버
JSON 응답 (code: 0 = 성공)
▼ JSON 응답 파싱 → 프론트엔드 렌더링
프론트엔드 렌더링
해시태그 목록 → 좌측 패널 리스트
비디오 데이터 → 우측 패널 임베드 카드
Rate Limit → 상단 도트 인디케이터
제한 Rate Limit 정책
| 엔드포인트 | 제한 | 윈도우 | 비고 |
|---|
| trending_list | 10회/분 | 60초 슬라이딩 | 인기 해시태그 목록 조회 |
| detail | 20회/분 | 60초 슬라이딩 | 해시태그 상세 조회 |
| video | 20회/분 | 60초 슬라이딩 | 인기 비디오 조회 |
슬라이딩 윈도우 방식: 각 요청 시점을 기록하고, 현재 시점으로부터 60초 이내의 요청 수를 카운트합니다.
제한 초과 시 대기 시간이 30초 이하면 자동 대기 후 재시도하고, 초과하면 사용자에게 안내 메시지를 표시합니다.
429 응답(서버 측 제한)을 받으면 2초 → 4초 → 8초 간격으로 지수 백오프 재시도를 수행합니다.
파일 주요 파일 구성
| 파일 | 역할 |
|---|
view/trending_hashtags.php | 프론트엔드 뷰 (HTML + CSS + JS) |
api/trending_hashtag_provider.php | API 라우터 + 각 엔드포인트 호출 함수 |
analyzer/DiscoveryRateLimiter.php | 파일 기반 Rate Limit 관리 클래스 |
config/tiktok_config.php | 인증 정보 (access_token, advertiser_id, bc_id) |