Minimal Widget Creator — Help
← Builder Setup guide

사용 방법

Worker는 한 번만 배포하면 됩니다. 같은 Worker에 여러 Widget ID를 저장하고 각각 /<id>.svg로 사용할 수 있습니다.

  1. 위젯을 디자인합니다

    네 모서리 문구, 색상, 날짜, 배경, 프레임을 설정합니다. {days}는 종료일로부터 지난 일수로 자동 치환됩니다.

  2. 배경 이미지를 준비합니다

    Local image는 브라우저 미리보기와 200×40 WebP 내보내기용입니다. 실제 배포 위젯에 배경을 넣으려면 공개 HTTPS 이미지 주소를 Hosted image URL에 넣습니다.

  3. Admin token을 만듭니다

    Generate token을 누르고 토큰을 보관합니다. ADMIN_TOKEN은 Builder의 위젯 생성·수정·삭제 권한을 보호합니다.

  4. Worker를 배포합니다

    Deploy Worker를 눌러 Worker 템플릿을 Cloudflare에 배포합니다. Worker 하나가 여러 위젯을 담당합니다.

  5. Cloudflare Secret을 확인합니다

    배포된 Worker에서 아래 Secret을 확인합니다. 배포 과정에서 자동으로 묻지 않았거나 값이 없다면 직접 추가합니다.

    Worker → Settings → Variables and Secrets
    ADMIN_TOKEN
    Builder에서 생성한 Admin token과 동일한 값
    DATA_TOKEN
    실시간 데이터 연동용 별도 랜덤 토큰. 실시간 연동을 쓰지 않아도 등록해 둘 수 있습니다.

  6. Worker 주소를 Builder에 연결합니다

    Worker base URL에 배포된 Worker 주소를 넣고, Admin token에는 같은 ADMIN_TOKEN 값을 입력합니다.

    https://your-worker.workers.dev
    또는 https://widgets.example.com

  7. 위젯을 Publish합니다

    Widget ID를 정하고 Publish / Update this ID를 누릅니다. 같은 ID를 다시 Publish하면 기존 위젯이 업데이트됩니다.

    qurare → https://widgets.example.com/qurare.svg
동적 placeholder

{days}는 Builder가 기본 제공하는 값입니다. Ended at을 기준으로 지난 일수를 Worker가 직접 계산하므로 외부 데이터가 필요 없습니다.

그 외에는 원하는 이름을 자유롭게 사용할 수 있습니다. 예를 들어 Worker에 rank4, points4, nickname 값을 저장해 두면 문구에서 각각 {rank4}, {points4}, {nickname}으로 불러옵니다.

{nickname}
{rank4} / {points4} pt

값을 넣을 때는 DATA_TOKEN으로 아래 endpoint에 JSON을 전송합니다. Worker는 이를 해당 위젯의 live KV 값으로 저장하고, 같은 이름의 placeholder를 치환합니다.

PUT /api/widgets/<id>/data
Authorization: Bearer <DATA_TOKEN>
{"nickname":"SDTR","rank4":"Master I","points4":567}

DATA_TOKEN은 실시간 값 갱신 전용이며, 위젯 생성·수정·삭제에 쓰는 ADMIN_TOKEN과 별개입니다.

기존 위젯 관리

Refresh list로 저장된 ID를 불러오고, Load this ID로 설정을 다시 불러옵니다. 같은 ID로 Publish하면 업데이트되고, Delete this ID는 위젯 설정과 해당 live data를 함께 삭제합니다.

문제가 생겼다면
Unauthorized
Cloudflare에 등록한 토큰과 요청에 사용한 토큰이 같은지 확인합니다.
Widget not found
Widget ID가 실제로 Publish되어 있는지 확인합니다.
동적 값이 안 나옴
placeholder 이름과 전송한 JSON key가 같은지, 최신 Worker가 배포되어 있는지 확인합니다.
배경이 안 보임
Hosted image URL이 공개 HTTPS 이미지인지 확인합니다.

ADMIN_TOKEN, DATA_TOKEN은 공개 저장소, 위젯 URL, SVG 안에 넣지 마세요. 공개 SVG를 보는 사람에게는 토큰이 필요하지 않습니다.