Bild-Proxy

Verwende den Bild-Proxy von Nowly, wenn Discord ein Präsenzbild nicht direkt von einem unterstützten externen CDN laden kann.

Wofür er gedacht ist

Der Bild-Proxy ist für einen bestimmten Fall vorgesehen: Eine Präsenz kann ein öffentliches Bild auf der Seite sehen, Discord kann es aber nicht zuverlässig von der ursprünglichen URL laden.

Das ist nützlich für Video-Vorschaubilder, Avatare, Poster oder Kategoriebilder von einem externen CDN, wenn:

• das Bild öffentlich und bereits im Browser sichtbar ist;
• die CDN-URL für Discord Rich Presence zu lang ist;
• Discord das direkte Bild ablehnt, die URL abläuft oder der Download fehlschlägt;
• die Präsenz statt des Dienstlogos ein zum Inhalt passendes Bild zeigen soll.

Dies ist kein universeller Bild-Proxy. Die API akzeptiert nur ausdrücklich zugelassene Dienste und Domains.

Funktionsweise

Der empfohlene Ablauf verwendet eine temporäre Kurz-URL:

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

Die Präsenz sendet die tatsächliche CDN-Bild-URL an die API. Die API prüft, ob der Dienst unterstützt wird, lädt das Bild herunter, überprüft MIME-Typ und Größe und speichert es vorübergehend im Cache. Sie gibt eine Kurz-URL zurück, zum Beispiel:

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

Diese URL liefert die Bilddaten direkt mit dem richtigen Content-Type. Sie ist für largeImageKey oder smallImageKey vorgesehen.

import { createCachedImageProxyUrl } from "@nowly/sdk"

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

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

Der Cache ist kurzlebig, derzeit fünf Minuten. Der Helper führt außerdem einen Cache im Arbeitsspeicher der Präsenz, damit die API nicht bei jeder Aktualisierung aufgerufen wird.

Direkter Endpunkt

Der ältere direkte Proxy bleibt für manuelle Tests oder bereits ausreichend kurze URLs verfügbar:

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

Die Parameter url und u müssen mit encodeURIComponent kodiert werden. Für Discord Rich Presence ist createCachedImageProxyUrl vorzuziehen, da Discord Bildschlüssel auf 300 Zeichen begrenzt.

Einrichtung in einer Präsenz

Ermittle zuerst die tatsächliche Bild-URL auf der Seite:

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
}

Übergib diese URL dann an den Helper, bevor du die Aktivität festlegst:

import { createCachedImageProxyUrl } from "@nowly/sdk"

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

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

Behalte immer eine Ersatzgrafik bei. Wenn die Seite kein Bild liefert, das Bild zu groß ist oder die Herkunft nicht zugelassen ist, sollte die Präsenz mit Assets.Logo oder einer lokalen Grafik weiter funktionieren.

Einen Dienst hinzufügen

Zugelassene Domains werden von der API geprüft, nicht von der Präsenz. Eine Präsenz kann nicht zur Laufzeit eine beliebige Domain über den Proxy abrufen. Es gibt keinen separaten Genehmigungsschritt und keine Änderung am API-Code: Trage die benötigten Hosts direkt in der metadata.json deiner Präsenz ein. Verwende denselben service-Wert (den Slug deiner Präsenz), den du an den Helper übergibst:

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

Die Angaben werden zusammen mit deiner übrigen metadata.json automatisch an die API veröffentlicht. Die API vertraut dieser Erklärung nur für die service-ID deiner eigenen Präsenz. Eine Präsenz kann keine Hostnamen für eine andere erklären; eine Anfrage ist nur erlaubt, wenn der Hostname der Ziel-URL tatsächlich zu einem erklärten Suffix passt.

Wenn dein PR imageProxy ändert, erkennt der Vorschau-Bot für Präsenzen dies automatisch, ergänzt im Kommentar einen Abschnitt Image Proxy Requested mit den erklärten Hostnamen und setzt das Label image-proxy. Vor dem Merge muss ein Reviewer dennoch bestätigen, dass die Hostnamen öffentlich und für den Proxy sicher sind. Erkläre im PR, warum Discord die direkte Bild-URL nicht nutzen kann und welches Bild Nutzende sehen werden.

Grenzen und Sicherheit

Der Proxy liefert nur öffentliche Bilder von Hosts, die eine geprüfte Präsenz erklärt hat. Er lehnt Nicht-HTTPS-URLs, Hosts ohne passenden erklärten Suffix, Antworten ohne Bildinhalt und zu große Dateien ab.

Die Endpunkte sind öffentlich und ohne Authentifizierung erreichbar (Präsenzen rufen sie direkt aus dem Browser auf, daher kann kein Geheimnis mitgesendet werden). Sie teilen sich das globale Ratenlimit der API; es gibt kein Kontingent pro Präsenz. Verwende den Proxy nicht für private Kontoinhalte, authentifizierte Ressourcen, Tracking-URLs, beliebige Nutzereingaben oder Inhalte, die keine Bilder sind.