Proxy obrazów

Użyj proxy obrazów Nowly, gdy Discord nie może pobrać obrazu obecności bezpośrednio z obsługiwanego zewnętrznego CDN.

Do czego służy

Proxy obrazów służy do konkretnego przypadku: obecność widzi publiczny obraz na stronie, ale Discord nie może niezawodnie pobrać go z pierwotnego adresu URL.

Przydaje się w przypadku miniaturek wideo, awatarów, plakatów i obrazów kategorii z zewnętrznego CDN, gdy:

• obraz jest publiczny i już widoczny w przeglądarce;
• adres URL CDN jest za długi dla Discord Rich Presence;
• Discord odrzuca bezpośredni obraz, adres wygasa lub pobieranie się nie udaje;
• obecność ma wyświetlać grafikę powiązaną z treścią zamiast samego logo usługi.

To nie jest uniwersalny serwer proxy obrazów. API przyjmuje wyłącznie jawnie dozwolone usługi i domeny.

Jak to działa

Zalecany sposób używa tymczasowego krótkiego adresu URL:

POST https://api.nowly.me/images-proxy
GET  https://api.nowly.me/images-proxy/<id>

Obecność wysyła do API właściwy adres obrazu w CDN. API sprawdza, czy usługa jest obsługiwana, pobiera obraz, weryfikuje typ MIME i rozmiar, a następnie tymczasowo zapisuje go w pamięci podręcznej. Zwraca krótki adres, na przykład:

https://api.nowly.me/images-proxy/abc123...

Ten adres zwraca bezpośrednio dane obrazu z poprawnym nagłówkiem Content-Type. Jest przeznaczony do largeImageKey lub smallImageKey.

import { createCachedImageProxyUrl } from "@nowly/sdk"

const image = await createCachedImageProxyUrl("tiktok", imageUrl)

await presence.setActivity({
  details: "Watching a video",
  largeImageKey: image ?? Assets.Logo,
})

Pamięć podręczna działa krótko, obecnie przez pięć minut. Funkcja pomocnicza przechowuje też dane w pamięci obecności, aby nie wywoływać API przy każdej aktualizacji.

Bezpośredni punkt końcowy

Starszy bezpośredni proxy nadal działa na potrzeby testów ręcznych lub adresów URL, które są już wystarczająco krótkie:

https://api.nowly.me/image-proxy?service=<service>&url=<encoded-url>
https://api.nowly.me/i?u=<encoded-url>

Parametry url i u muszą być zakodowane przez encodeURIComponent. Do Discord Rich Presence wybierz createCachedImageProxyUrl, ponieważ Discord ogranicza klucze obrazów do 300 znaków.

Konfiguracja w obecności

Najpierw pobierz właściwy adres obrazu ze strony:

const getPoster = (video: HTMLVideoElement): string | undefined => {
  if (video.poster) return video.poster

  const image = video.closest("[data-video]")?.querySelector("img")
  return image?.getAttribute("src") ?? undefined
}

Następnie przekaż ten adres do funkcji pomocniczej przed ustawieniem aktywności:

import { createCachedImageProxyUrl } from "@nowly/sdk"

const poster = await createCachedImageProxyUrl("tiktok", getPoster(video))

await presence.setActivity({
  details: "Watching a video",
  largeImageKey: poster ?? Assets.Logo,
})

Zawsze zachowuj grafikę zastępczą. Jeśli strona nie ma obrazu, obraz jest za duży albo źródło nie jest dozwolone, obecność powinna nadal działać z Assets.Logo lub lokalną grafiką.

Dodawanie usługi

Dozwolone domeny sprawdza API, a nie obecność. Obecność nie może używać proxy dla dowolnej domeny przez samo wysłanie żądania podczas działania. Nie ma osobnego etapu zatwierdzania ani konieczności zmiany kodu API: zadeklaruj potrzebne hosty bezpośrednio w pliku metadata.json swojej obecności. Użyj tej samej wartości service (identyfikatora obecności), którą przekazujesz funkcji pomocniczej:

"imageProxy": {
  "hostSuffixes": ["netflix.com", "nflxvideo.net", "nflximg.net"],
  "headers": { "Referer": "https://www.netflix.com/" }
}

Deklaracja jest automatycznie publikowana w API wraz z pozostałą częścią metadata.json. API ufa jej tylko dla identyfikatora service Twojej własnej obecności. Obecność nie może deklarować hostów w imieniu innej obecności, a żądanie jest dozwolone tylko wtedy, gdy nazwa hosta docelowego adresu URL naprawdę pasuje do jednego z zadeklarowanych sufiksów.

Gdy PR zmienia imageProxy, bot podglądu obecności automatycznie to wykrywa, dodaje w komentarzu sekcję Image Proxy Requested z listą hostów i etykietę image-proxy. Przed scaleniem osoba recenzująca musi jeszcze potwierdzić, że hosty są publiczne i bezpieczne dla proxy. W opisie PR wyjaśnij, dlaczego Discord nie może użyć bezpośredniego adresu obrazu i jaki obraz zobaczy użytkownik.

Limity i bezpieczeństwo

Proxy udostępnia tylko publiczne obrazy z hostów zadeklarowanych przez sprawdzoną obecność. Odrzuca adresy inne niż HTTPS, hosty niepasujące do zadeklarowanych sufiksów, odpowiedzi niebędące obrazami i zbyt duże pliki.

Punkty końcowe są publiczne i nie wymagają uwierzytelnienia (obecności wywołują je bezpośrednio z przeglądarki, więc nie przesyłają sekretów). Dzielą globalny limit żądań API; nie ma osobnego limitu na obecność. Nie używaj proxy do prywatnych treści z kont, zasobów wymagających uwierzytelnienia, adresów śledzących, dowolnych danych wejściowych użytkownika ani treści niebędących obrazami.