제품 출시 반응을 추적하는 주간 TikTok 보고서 만들기

앱이나 새 기능을 출시한 뒤에는 짧은 동영상 곳곳으로 피드백이 빠르게 흩어집니다. 마케터가 영상 몇 개를 직접 찾아 채팅방에 링크를 공유하고 나면, 분석 담당자는 어떤 게시물을 이미 집계했는지, 조회수가 어떻게 달라졌는지 파악하기 어려워집니다. 실용적인 해결책은 일관된 검색어 몇 가지로 검색 결과를 정기적으로 수집하고, 원본 응답을 보관하며, 확인된 필드만 사용해 보고서를 만드는 것입니다.

이 안내서에서는 구체적인 사례를 위해 수집 흐름을 설정합니다. 팀이 새 기능을 출시했고, 제품 이름이나 핵심 기능 또는 일반적인 사용자 문제를 설명에 포함한 공개 TikTok 동영상을 매주 추적하려 한다고 가정해 보겠습니다. 이는 검색으로 발견한 표본을 모니터링하는 방식입니다. API는 검색어와 매개변수에 따른 결과를 반환할 뿐, 출시와 관련된 모든 게시물의 목록을 보장하지 않습니다.

먼저 팀에 필요한 신호를 정하세요

조회수가 많다는 사실만으로는 다음에 무엇을 해야 할지 알기 어렵습니다. 팀에는 어떤 질문이 반복되는지, 사람들이 어떤 사용 사례를 보여주는지, 어떤 영상이 눈에 띄는 공개 반응을 얻는지 파악하는 편이 더 유용합니다. 따라서 먼저 검색 문구를 몇 개 정하고 보고서에 포함할 필드를 결정하세요.

예를 들어 게시물 예약 도구를 출시했다면 ‘제품 이름’, ‘콘텐츠 예약 도구’, ‘TikTok 예약하는 방법’이라는 검색어를 확인할 수 있습니다. 문구는 사람들이 같은 주제를 서로 다른 방식으로 표현하는 경우를 반영해야 합니다. 이후의 데이터를 동일한 설정으로 비교할 수 있도록 모니터링 시작 날짜와 지역을 검색어와 함께 기록하세요.

최소한의 표에는 수집 시각, 검색어, 동영상 ID, 링크, 설명, 작성자 이름, 작성자 ID, 확인 가능한 조회수·좋아요·댓글 수를 넣을 수 있습니다. TikTok Scraper API 문서에는 검색 결과 필드로 aweme_id, desc, share_url, 작성자 정보와 일부 통계가 나와 있습니다. 구체적인 필드는 각 객체에서 확인해야 하며, 일부 지표는 누락될 수 있습니다.

문서화된 검색 기능 연결하기

동영상을 검색하려면 기본 주소 https://tiktok.evelode.com의 GET 경로 /searchVideo를 사용하세요. 문서에 따르면 필수 매개변수는 keyword이며, 선택 매개변수로 count, cursor, date_posted, sort_by, region, cache_timeout을 사용할 수 있습니다. 날짜 필터의 허용 값에는 this-week가, 정렬 기준에는 relevance, most-liked, date-posted가 포함됩니다. 각 매개변수의 목적과 이름은 TikTok API 경로 안내서에서 확인하세요.

라이선스 키는 쿼리 매개변수 license_key로 전달합니다. 운영 스크립트에서는 환경 변수 JSONSCRAPER_TIKTOK_LICENSE_KEY에서 키를 읽고, 소스 코드에 비밀값을 기록하거나 로그에 출력하지 마세요. 다음 예제는 Python 3.8 이상을 대상으로 하며 requests 패키지를 사용합니다.

import os
import requests

BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]


def search_videos(keyword, cursor=None):
    params = {
        "license_key": API_KEY,
        "keyword": keyword,
        "count": 20,
        "date_posted": "this-week",
        "sort_by": "date-posted",
        "region": "US",
    }
    if cursor is not None:
        params["cursor"] = cursor

    response = requests.get(
        f"{BASE_URL}/searchVideo",
        params=params,
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("TikTok API가 ok가 아닌 상태를 반환했습니다")

    return payload["tiktok"]


result = search_videos("content planning app")
print("발견한 객체 수:", len(result.get("aweme_list", [])))

이 스크립트는 HTTP 오류와 응답의 최상위 상태를 확인합니다. HTTP 요청이 성공했다고 해서 검색 결과에 동영상이 있다는 뜻은 아닙니다. 결과가 없으면 목록이 비어 있을 수 있습니다. 처음 실행할 때는 응답 전체를 안전한 저장소에 보관해 실제 객체와 정규화된 필드 표를 비교하는 것이 좋습니다.

두 가지 검색 응답 형식 모두 처리하기

검색 결과 구조에는 중요한 특징이 있습니다. 동영상이 tiktok.aweme_list에 직접 들어 있을 수도 있고, tiktok.search_item_list[].aweme_info 안에 포함될 수도 있습니다. 첫 번째 목록만 읽는 처리기는 두 번째 형식에 들어 있는 결과를 놓칠 수 있습니다.

두 구조를 모두 지원하고, 중첩된 동영상 객체가 없는 항목은 문제없이 건너뛰는 간단한 정규화 함수를 추가하세요.

def extract_awemes(tiktok):
    items = list(tiktok.get("aweme_list") or [])

    for item in tiktok.get("search_item_list") or []:
        aweme = item.get("aweme_info")
        if aweme:
            items.append(aweme)

    return items


def normalize(aweme, keyword, collected_at):
    author = aweme.get("author") or {}
    stats = aweme.get("statistics") or {}

    return {
        "collected_at": collected_at,
        "keyword": keyword,
        "video_id": aweme.get("aweme_id"),
        "posted_at": aweme.get("create_time"),
        "description": aweme.get("desc"),
        "share_url": aweme.get("share_url"),
        "author_id": author.get("uid"),
        "author_name": author.get("nickname"),
        "views": stats.get("play_count"),
        "likes": stats.get("digg_count"),
        "comments": stats.get("comment_count"),
        "shares": stats.get("share_count"),
    }

값이 없으면 None으로 둡니다. 이를 0으로 바꾸지 마세요. 0은 측정된 값이지만, None은 해당 필드가 응답에 포함되지 않았다는 사실을 나타냅니다. 이 차이는 평균, 비율 및 팀이 내리는 모든 결론에 영향을 줍니다.

현재 스냅샷뿐 아니라 기록도 보관하기

변화를 확인하려면 관측 시점별로 별도의 기록을 저장하세요. 동영상 ID로 게시물 중복을 제거할 수 있지만, 이 ID를 기준으로 기록을 삭제해서는 안 됩니다. 다음 수집 때 같은 영상이 다시 나타나면 새로운 관측 지점이 생깁니다. 예를 들어 관측 테이블의 고유 키를 video_id와 collected_at으로 구성하고, 확인하기 쉽도록 해당 기록에 링크와 설명도 저장할 수 있습니다.

프로토타입에는 다음과 같은 최소한의 SQLite 스키마를 사용할 수 있습니다.

import sqlite3

conn = sqlite3.connect("tiktok_observations.sqlite3")
conn.execute("""
CREATE TABLE IF NOT EXISTS observations (
    video_id TEXT NOT NULL,
    collected_at TEXT NOT NULL,
    keyword TEXT NOT NULL,
    posted_at INTEGER,
    description TEXT,
    share_url TEXT,
    author_id TEXT,
    author_name TEXT,
    views INTEGER,
    likes INTEGER,
    comments INTEGER,
    shares INTEGER,
    PRIMARY KEY (video_id, collected_at, keyword)
)
""")
conn.commit()

실제 운영에서는 수집 시각을 UTC로 정규화하고, 원본 JSON을 별도로 보관하며, 스키마 버전 열을 추가하세요. 익숙한 형식과 다른 새 객체가 들어왔을 때 원본 응답으로 변환 과정을 다시 확인할 수 있습니다. 여러 검색어에서 발견된 게시물은 별도의 관련 테이블에 일치한 검색어를 저장하거나 보고서 작성 과정에서 통합하세요.

페이지네이션: 응답에 담긴 커서로만 이어서 검색하기

cursor 매개변수는 검색을 이어가는 데 사용됩니다. 이전 응답에서 값을 가져와 변환하지 않고 그대로 전달하세요. has_more가 더 이상 계속할 결과가 없다고 나타내거나 설정된 한도에 도달하면 작업을 끝냅니다. 커서는 불투명한 값으로 취급해야 합니다. 직접 계산하거나 페이지 번호로 대체하지 마세요.

def collect_pages(keyword, max_pages=3):
    cursor = None
    collected = []

    for _ in range(max_pages):
        page = search_videos(keyword, cursor)
        collected.extend(extract_awemes(page))

        if not page.get("has_more"):
            break
        cursor = page.get("cursor")
        if cursor is None:
            break

    return collected

페이지 수를 제한하면 정기 작업에서 요청량을 예측하기 쉽습니다. 실행 로그에 페이지 수와 has_more 값을 기록하면 표본 규모를 보고할 때 맥락을 제공할 수 있습니다. 페이지네이션을 사용하더라도 결과는 API 응답과 지정된 수집 한도를 바탕으로 한 것이며, 플랫폼 전체 게시물의 추정치가 아닙니다.

반복 가능한 보고서 만들기

팀에 더 자주 신호가 필요하다면 매주 또는 그보다 자주 수집 작업을 실행하도록 예약하세요. 실행마다 검색어 목록, 매개변수, 시각, 수집한 객체 수, 고유 ID 수를 기록합니다. 이번 실행에서 처음 발견한 게시물과 이전에 이미 발견한 게시물도 따로 집계하세요.

보고서에는 다음과 같은 네 가지 간단한 항목이 유용합니다.

• 새 동영상: 발견에 사용한 검색어, 게시 날짜, 설명 및 링크.
• 반복되는 주제: ‘설정 오류’, ‘기능 요청’, ‘사용 사례 소개’처럼 직접 정의한 범주로 설명을 분류한 결과.
• 공개 반응: 확인 가능한 조회수, 좋아요, 댓글, 공유 수를 관측 시각과 함께 표시.
• 검토할 신호: 새롭게 등장한 표현, 자주 나오는 질문 또는 직원이 살펴볼 만한 동영상.

응답의 지표 의미와 최신성이 확인되지 않았다면 두 스냅샷 간 차이를 ‘새 좋아요 수’라고 부르지 마세요. 대신 ‘가장 최근에 받은 응답의 지표 값’과 ‘저장된 스냅샷 간 차이’라고 표현하는 것이 정확합니다. 그러면 팀은 무엇을 계산했는지 알 수 있고, 의사결정 전에 원본 게시물을 열어볼 수 있습니다.

수집을 대체하는 것이 아니라 분류 단계에 AI 추가하기

정규화한 뒤 동영상 설명을 모델에 보내 미리 정한 범주로 분류할 수 있습니다. 필요한 텍스트 필드만 보내고 범주, 간단한 근거, 신뢰도, 분류의 근거가 된 설명의 일부를 구조화된 결과로 반환하도록 요청하세요. 분석 담당자가 논란의 여지가 있는 사례를 확인할 수 있도록 원본 게시물과 분류 결과를 함께 보관하세요.

운영 흐름은 단순하게 유지할 수 있습니다. 스케줄러가 수집을 시작하고, Python이 응답을 확인해 JSON을 저장하며, 별도 작업이 새 기록을 정규화합니다. 그런 다음 분류기가 새 설명만 처리하고, 데이터베이스에서 보고서를 만들어 팀이 지정한 채널로 보냅니다. TikTok Scraper API는 검색 데이터를 제공하며, 분류와 보고서 전달은 Python, n8n 또는 Make로 구현할 수 있는 자체 통합 로직입니다.

잡음을 줄이려면 모델에 보내기 전에 범주 사전을 정하고, 사람이 직접 분류한 표본을 정기적으로 점검하세요. 짧거나 모호한 설명은 억지로 범주에 넣지 말고 ‘맥락 부족’ 상태를 사용할 수 있습니다. AI 분류는 검토 대상을 정리하는 데 도움이 될 뿐입니다. 사용자 문제가 무엇인지 결론을 내리려면 게시물을 직접 읽고 여러 관측 결과를 비교해야 합니다.

오류와 재시도, 키를 안전하게 다루는 방법

네트워크 요청은 시간 초과, 일시적인 오류 또는 JSON으로 파싱할 수 없는 응답으로 실패할 수 있습니다. 요청, HTTP 상태 코드 확인, JSON 파싱, 최상위 상태 확인, 정규화, 저장 단계를 분리하세요. 일시적인 실패에는 대기 시간을 점차 늘리는 제한된 재시도 횟수를 적용하고, 영구 오류는 실행을 성공으로 표시하지 않은 채 나중에 검토할 수 있도록 기록하세요.

키는 실행 환경의 비밀 정보 관리 시스템이나 환경 변수에 보관하세요. API는 license_key를 쿼리 문자열로 받으므로 전체 URL이나 요청 매개변수를 기록하지 마세요. 그 안에 비밀값이 포함되기 때문입니다. 진단을 위해서는 경로, 응답 코드, 소요 시간, 검색어, 작업 ID를 기록하되 로그에서 키는 제거하세요.

사용 목적과 플랫폼 이용 조건에 맞춰 실행 일정과 표본 규모를 설정하세요. 공개 데이터 수집은 분석에 실제로 필요한 범위로 제한해야 합니다. 설명, 링크, 작성자 ID를 저장하는 방식은 팀 내부 규정에 명시하세요. API 응답과 지표는 불완전할 수 있고 관측 시점마다 달라질 수 있으므로, 보고서에는 각 행의 수집 시각과 출처를 보존해야 합니다.

결과: 수동으로 모은 링크에서 검증 가능한 기록으로

설정을 마치면 팀은 새로 발견한 동영상 목록, 감사를 위한 원본 응답, 확인 가능한 공개 지표 표, 반복되는 주제 개요를 정기적으로 받게 됩니다. 이를 통해 새 기능에 대한 질문을 더 빨리 파악하고, 사용자 사례를 찾으며, 사람이 직접 분석할 게시물을 고를 수 있습니다. 스냅샷을 비교하면 이미 발견한 동영상의 저장된 값이 어떻게 달라지는지 확인할 수 있고, 검색어 기록을 보면 표본이 어떤 방식으로 만들어졌는지 알 수 있습니다.

검색어 하나와 적은 페이지 수로 시작해 실제 응답 구조를 확인한 다음, 다른 표현과 실행 일정을 추가하세요. 프로토타입을 운영 환경으로 옮기기 전에 중복 제거, 보관, 오류 처리 규칙을 정하세요. 최신 경로와 매개변수는 공식 API 문서에서 확인할 수 있습니다. 기능 설명과 테스트 시작 방법은 TikTok Scraper API 페이지에 안내되어 있습니다.