Skip to content
Wszystkie wpisy
Blog·6 marca 2026

Jak działa API renderowania Screenshots Live — Praktyczny przewodnik po automatyzacji kart sklepowych

Techniczny przewodnik po tym, jak API renderowania Screenshots Live przetwarza szablony, stosuje przesłonięcia YAML i generuje gotowe do sklepu zrzuty ekranu — z prawdziwymi przykładami kodu i wzorcami CI/CD dla konfiguracji whitelabel.

Co obejmuje ten artykuł

Jeśli tworzysz aplikacje whitelabel — lub nawet tylko jedną aplikację z wieloma kartami w sklepie — prawdopodobnie natrafiłeś już na problem ze zrzutami ekranu. Apple chce zrzutów ekranu dla każdego rozmiaru urządzenia. Google Play ma swój własny zestaw. Obsługa trzech języków trzykrotnie zwiększa nakład pracy. Teraz pomnóż to przez liczbę wariantów marki, które utrzymujesz.

Poprzedni artykuł wyjaśniał, dlaczego Screenshots Live istnieje. Ten jest praktycznym kontynuowaniem: jak API renderowania jest zaprojektowane, czego oczekuje i jak podłączyć je do pipeline'u build, aby zrzuty ekranu przestały być zadaniem ręcznym.

Jak zaprojektowano pipeline renderowania

System renderowania nie jest synchronicznym endpointem w stylu "wyślij żądanie, otrzymaj obraz". Jest to pipeline oparty na zadaniach, co ma znaczenie, gdy renderujesz dziesiątki lub setki zrzutów ekranu wsadowo.

  1. Wysyłasz żądanie renderowania z ID szablonu i opcjonalnymi przesłonięciami YAML (tekst, zrzuty ekranu, ramki urządzeń — wszystko oznaczone jako wymienne).
  2. Walidacja — system sprawdza, czy twój szablon istnieje, czy jesteś jego właścicielem i czy każde pole, które przesłaniasz, jest faktycznie dozwolone.
  3. Kolejkowanie — zadanie trafia do kolejki BullMQ wspieranej przez Redis. Twoje wywołanie API zwraca natychmiast jobId i status Pending.
  4. Renderowanie — worker oparty na Rust pobiera zadanie, pobiera szablon i obrazy (z pamięcią podręczną LRU dla powtarzających się renderowań), ładuje czcionki, renderuje canvas używając Skia i generuje wynik.
  5. Pakowanie — wyrenderowane obrazy są pakowane do ZIP i przesyłane do magazynu obiektów.
  6. Pobieranie — odpytujesz endpoint statusu. Gdy jest Completed, uderzasz w endpoint pobierania, aby uzyskać wstępnie podpisany URL (ważny przez 1 godzinę).

Asynchroniczny design jest celowy. Gdy musisz wyrenderować 50 szablonów dla release'u, wysyłasz je wszystkie, a potem zbierasz wyniki. Bez blokowania, bez timeoutów.

Uwierzytelnianie

Potrzebujesz konta Pro, aby uzyskać dostęp do API renderowania. Utwórz klucz API z pulpitu nawigacyjnego — będzie wyglądał jak sa_live_.... Każde żądanie używa go jako tokenu Bearer:

Authorization: Bearer sa_live_your_key_here

Szablony: Jak są zbudowane

Wszystko obraca się wokół szablonów. Szablon to canvas, który budujesz w edytorze wizualnym — umieszczasz bloki tekstu, ramki urządzeń, obrazy i ustawiasz tła. Każdy element na canvasie to item z unikalnym UUID.

W automatyzacji kluczową koncepcją są pola wymienne. Nie każda właściwość każdego elementu jest nadpisywalna przez API. Administrator konfiguruje, które pola można wymieniać — zawartość tekstu, rodzinę czcionek, rozmiar czcionki, kolory, URLe zrzutów ekranu, IDy ramek urządzeń i tak dalej. To celowe ograniczenie: zapobiega przypadkowemu uszkodzeniu układu przez konsumentów API poprzez zmianę pozycji lub rozmiarów, które projektant zablokował.

Pomyśl o tym jak o umowie między projektantem a pipeline'em: projektant jest właścicielem układu, pipeline jest właścicielem treści.

System przesłonięć YAML

To serce API. Zamiast renderować szablon dokładnie tak, jak został zapisany, wysyłasz POST z YAML, który nadpisuje określone pola w określonych elementach.

Krok 1: Pobierz scaffold YAML

Każdy szablon ma endpoint scaffold, który zwraca wszystkie wymienne pola jako skomentowany YAML:

curl -H "Authorization: Bearer sa_live_your_key_here" \
  https://api.screenshots.live/templates/YOUR_TEMPLATE_ID/yaml

Krok 2: Wyślij renderowanie

curl -X POST https://api.screenshots.live/render/api \
  -H "Authorization: Bearer sa_live_your_key_here" \
  -H "Content-Type: text/yaml" \
  -d 'templateId: "550e8400-e29b-41d4-a716-446655440000"
items:
  - itemId: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    type: Text
    text: "Śledź swoje dostawy"
    color: "#1A73E8"'

Krok 3: Sprawdź status

curl -H "Authorization: Bearer sa_live_your_key_here" \
  https://api.screenshots.live/render/api/JOB_ID

Status przechodzi przez Pending → Active → Completed (lub Failed, jeśli coś poszło nie tak). Dla większości szablonów renderowanie zajmuje kilka sekund.

Krok 4: Pobierz

curl -H "Authorization: Bearer sa_live_your_key_here" \
  https://api.screenshots.live/render/JOB_ID/download

Zwraca wstępnie podpisany URL. Pobierany plik to ZIP zawierający wyrenderowane obrazy.

Bezpośrednie przesyłanie zrzutów ekranu

Nie musisz hostować swoich zrzutów ekranu gdzieś tylko po to, żeby przekazać URL. Endpoint /render/api/with-pictures akceptuje przesyłanie multipart. Możesz dołączyć do 200 plików, każdy do 10 MB. To sprawia, że API jest praktyczne do CI/CD — twój pipeline przechwytuje zrzuty ekranu i wysyłasz je bezpośrednio do renderowania bez potrzeby pośredniego przechowywania.

Przykład z życia wzięty: Pipeline whitelabel

Utrzymujesz 5 marek whitelabel, każda potrzebuje zrzutów ekranu w App Store w 3 językach dla 5 kluczowych ekranów. To 75 wyrenderowanych obrazów na release. Twój projektant stworzył jeden szablon na ekran w edytorze, z tekstem nagłówka i ramką urządzenia oznaczonymi jako wymienne. Twój pipeline CI przechwytuje surowe zrzuty ekranu na markę i lokalizację używając snapshot/screengrab Fastlane'a. Projekt asynchroniczny pomaga — zgłoszenia są szybkie, rzeczywiste renderowanie odbywa się w tle.

Wymiana ramek urządzeń

Ramki urządzeń to nakładki mockupów — iPhone 16 Pro, Pixel 9, iPad Air, Galaxy S24. Są wstępnie załadowane na twoim koncie i odwoływane przez UUID. Ten sam szablon może renderować z różnymi ramkami urządzeń poprzez nadpisanie frameId. W ten sposób obsługujesz podział App Store vs Google Play. Ten sam układ szablonu, ten sam zrzut ekranu, inna ramka. Wyślij dwa zadania renderowania — jedno z ramką iPhone, jedno z ramką Pixel — i obejmiesz oba sklepy z jednego szablonu.

Limity żądań i przydziały

  • API renderowania: 5 żądań na 60 sekund
  • Sprawdzanie statusu: 60 żądań na 60 sekund
  • Dzienne renderowania: 100 dziennie w tierze Pro
  • Przesyłanie obrazów: maks. 200 plików na żądanie, 10 MB każdy

Walidacja YAML

Parser YAML jest celowo rygorystyczny: bez kotwic, bez aliasów, bez niestandardowych tagów, maks. 1 MB. Jeśli coś jest nie tak, komunikat o błędzie mówi dokładnie co — zła nazwa pola, pole nie jest wymienne, nieprawidłowy format UUID, URL wskazujący na prywatny zakres IP. Jest zaprojektowany, aby szybko i wyraźnie zawieść, co ma znaczenie podczas debugowania pipeline'u CI o 23:00.