Görsel proxy'si

Discord, desteklenen harici bir CDN'deki presence görselini doğrudan yükleyemediğinde Nowly görsel proxy'sini kullan.

Ne için kullanılır?

Görsel proxy'si belirli bir durum için tasarlanmıştır: Presence, sayfada herkese açık bir görseli görebilir ancak Discord görseli asıl URL'den güvenilir şekilde yükleyemez.

Harici CDN'de sunulan video küçük resimleri, avatarlar, afişler veya kategori görselleri için şu durumlarda işe yarar:

• görsel herkese açıktır ve tarayıcıda zaten görüntülenir;
• CDN URL'si Discord Rich Presence için fazla uzundur;
• Discord doğrudan görseli reddeder, URL'nin süresi dolar veya indirme başarısız olur;
• presence yalnızca hizmet logosu yerine içerikle ilgili görsel göstermelidir.

Bu genel amaçlı bir görsel proxy'si değildir. API yalnızca açıkça izin verilmiş hizmetleri ve alan adlarını kabul eder.

Nasıl çalışır?

Önerilen akış geçici ve kısa bir URL kullanır:

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

Presence, gerçek CDN görsel URL'sini API'ye gönderir. API hizmetin desteklendiğini kontrol eder, görseli indirir, MIME türü ile boyutunu doğrular ve geçici olarak önbelleğe alır. Şuna benzer kısa bir URL döndürür:

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

Bu URL görsel baytlarını doğru Content-Type ile doğrudan döndürür. largeImageKey veya smallImageKey için tasarlanmıştır.

import { createCachedImageProxyUrl } from "@nowly/sdk"

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

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

Önbellek kısa sürelidir, şu anda beş dakikadır. Yardımcı işlev, API'nin her güncellemede çağrılmaması için presence içinde ayrıca bellek içi önbellek tutar.

Doğrudan uç nokta

Eski doğrudan proxy, manuel testler veya zaten yeterince kısa olan URL'ler için kullanılabilir:

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

url ve u parametreleri encodeURIComponent ile kodlanmalıdır. Discord görsel anahtarlarını 300 karakterle sınırladığı için Rich Presence'da createCachedImageProxyUrl tercih edilmelidir.

Presence içinde kurulum

Önce sayfadan gerçek görsel URL'sini al:

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
}

Ardından etkinliği ayarlamadan önce URL'yi yardımcı işlevden geçir:

import { createCachedImageProxyUrl } from "@nowly/sdk"

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

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

Her zaman yedek bir görsel tut. Sayfada görsel yoksa, görsel fazla büyükse veya kaynak izinli değilse presence Assets.Logo ya da yerel bir görselle çalışmaya devam etmelidir.

Hizmet ekleme

İzin verilen alan adları presence tarafından değil, API tarafından kontrol edilir. Presence, çalışma sırasında istekte bulunarak keyfî bir alan adını proxy üzerinden kullanamaz. Ayrı bir onay adımı veya API kodu değişikliği gerekmez: Presence'ın ihtiyaç duyduğu hostları kendi metadata.json dosyasında bildir. Yardımcı işleve verdiğin service değeriyle (presence slug'ı) aynı değeri kullan:

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

Bu bildirim, metadata.json dosyanın diğer içerikleriyle birlikte otomatik olarak API'ye yayımlanır. API bu bildirime yalnızca kendi presence'ının service kimliği için güvenir. Bir presence başka bir presence adına host adı bildiremez; istek ancak hedef URL'nin host adı bildirilen son eklerden biriyle gerçekten eşleşirse kabul edilir.

PR'ında imageProxy değiştiğinde presence önizleme botu bunu otomatik algılar, yorumuna bildirilen hostları listeleyen Image Proxy Requested bölümünü ekler ve image-proxy etiketini uygular. Bir incelemeci, birleştirme öncesinde hostların herkese açık ve proxy için güvenli olduğunu yine de doğrulamalıdır. Discord'un doğrudan görsel URL'sini neden kullanamadığını ve kullanıcının hangi görseli göreceğini PR açıklamasında belirt.

Sınırlar ve güvenlik

Proxy yalnızca incelenmiş bir presence'ın bildirdiği hostlardan herkese açık görseller sunar. HTTPS olmayan URL'leri, bildirilen son eklerle eşleşmeyen hostları, görsel olmayan yanıtları ve fazla büyük dosyaları reddeder.

Uç noktalar herkese açıktır ve kimlik doğrulaması gerektirmez (presence'lar bunları doğrudan tarayıcıdan çağırdığı için eklenecek bir gizli bilgi yoktur). API'nin genel hız sınırını paylaşırlar; presence başına ayrı kota yoktur. Proxy'yi özel hesap içerikleri, kimlik doğrulaması gerektiren kaynaklar, takip URL'leri, keyfî kullanıcı girdileri veya görsel olmayan içerikler için kullanma.