Διακομιστής μεσολάβησης εικόνων

Χρησιμοποιήστε τον διακομιστή μεσολάβησης εικόνων του Nowly όταν το Discord δεν μπορεί να φορτώσει απευθείας μια εικόνα παρουσίας από υποστηριζόμενο εξωτερικό CDN.

Σε τι χρησιμεύει

Ο διακομιστής μεσολάβησης εικόνων προορίζεται για μια συγκεκριμένη περίπτωση: μια παρουσία βλέπει μια δημόσια εικόνα στη σελίδα, αλλά το Discord δεν μπορεί να τη φορτώσει αξιόπιστα από την αρχική διεύθυνση URL.

Είναι χρήσιμος για μικρογραφίες βίντεο, άβαταρ, αφίσες ή εικόνες κατηγοριών από εξωτερικό CDN όταν:

• η εικόνα είναι δημόσια και ήδη ορατή στο πρόγραμμα περιήγησης·
• η διεύθυνση URL του CDN είναι υπερβολικά μεγάλη για το Discord Rich Presence·
• το Discord απορρίπτει την απευθείας εικόνα, η διεύθυνση λήγει ή η λήψη αποτυγχάνει·
• η παρουσία χρειάζεται εικόνα σχετική με το περιεχόμενο αντί μόνο για το λογότυπο της υπηρεσίας.

Δεν πρόκειται για διακομιστή μεσολάβησης εικόνων γενικής χρήσης. Το API δέχεται μόνο ρητά επιτρεπόμενες υπηρεσίες και περιοχές δικτύου.

Πώς λειτουργεί

Η συνιστώμενη ροή χρησιμοποιεί μια προσωρινή σύντομη διεύθυνση URL:

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

Η παρουσία στέλνει στο API την πραγματική διεύθυνση της εικόνας στο CDN. Το API ελέγχει αν υποστηρίζεται η υπηρεσία, κατεβάζει την εικόνα, ελέγχει τον τύπο MIME και το μέγεθός της και την αποθηκεύει προσωρινά στην κρυφή μνήμη. Επιστρέφει μια σύντομη διεύθυνση όπως:

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

Αυτή η διεύθυνση επιστρέφει απευθείας τα δεδομένα της εικόνας με τον σωστό Content-Type. Προορίζεται για largeImageKey ή smallImageKey.

import { createCachedImageProxyUrl } from "@nowly/sdk"

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

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

Η διάρκεια της κρυφής μνήμης είναι μικρή, επί του παρόντος πέντε λεπτά. Το βοηθητικό πρόγραμμα διατηρεί επίσης κρυφή μνήμη στη μνήμη της παρουσίας, ώστε να μην καλεί το API σε κάθε ενημέρωση.

Απευθείας τελικό σημείο

Ο παλαιότερος απευθείας proxy παραμένει διαθέσιμος για χειροκίνητες δοκιμές ή διευθύνσεις URL που είναι ήδη αρκετά σύντομες:

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

Οι παράμετροι url και u πρέπει να κωδικοποιούνται με encodeURIComponent. Για το Discord Rich Presence προτιμήστε το createCachedImageProxyUrl, επειδή το Discord περιορίζει τα κλειδιά εικόνας σε 300 χαρακτήρες.

Ρύθμιση σε μια παρουσία

Πρώτα, πάρτε την πραγματική διεύθυνση της εικόνας από τη σελίδα:

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
}

Έπειτα, περάστε τη διεύθυνση στο βοηθητικό πρόγραμμα πριν ορίσετε τη δραστηριότητα:

import { createCachedImageProxyUrl } from "@nowly/sdk"

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

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

Διατηρείτε πάντα μια εφεδρική εικόνα. Αν η σελίδα δεν έχει εικόνα, η εικόνα είναι πολύ μεγάλη ή η προέλευση δεν επιτρέπεται, η παρουσία πρέπει να συνεχίζει να λειτουργεί με Assets.Logo ή μια τοπική εικόνα.

Προσθήκη υπηρεσίας

Οι επιτρεπόμενοι τομείς ελέγχονται από το API, όχι από την παρουσία. Μια παρουσία δεν μπορεί να χρησιμοποιήσει τον proxy για οποιονδήποτε τομέα απλώς ζητώντας το κατά την εκτέλεση. Δεν απαιτείται ξεχωριστή έγκριση ούτε αλλαγή στον κώδικα του API: δηλώστε τους απαιτούμενους κεντρικούς υπολογιστές στο δικό της metadata.json, χρησιμοποιώντας την ίδια τιμή service (το slug της παρουσίας) που περνάτε στο βοηθητικό πρόγραμμα:

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

Αυτά δημοσιεύονται αυτόματα στο API μαζί με το υπόλοιπο metadata.json. Το API εμπιστεύεται τη δήλωση μόνο για το service της δικής σας παρουσίας. Μια παρουσία δεν μπορεί να δηλώσει ονόματα κεντρικών υπολογιστών για άλλη παρουσία και ένα αίτημα επιτρέπεται μόνο αν το όνομα του στόχου ταιριάζει πραγματικά σε ένα από τα δηλωμένα επιθήματα.

Όταν το PR σας αλλάζει το imageProxy, το bot προεπισκόπησης παρουσιών το εντοπίζει αυτόματα, προσθέτει στην απάντησή του ενότητα Image Proxy Requested με τα δηλωμένα ονόματα και εφαρμόζει την ετικέτα image-proxy. Πριν από τη συγχώνευση, ένας reviewer πρέπει να επιβεβαιώσει ότι οι κεντρικοί υπολογιστές είναι δημόσιοι και ασφαλείς για χρήση μέσω proxy. Εξηγήστε στο PR γιατί το Discord δεν μπορεί να χρησιμοποιήσει την απευθείας URL και ποια εικόνα θα δει ο χρήστης.

Όρια και ασφάλεια

Ο proxy εξυπηρετεί μόνο δημόσιες εικόνες από κεντρικούς υπολογιστές που έχει δηλώσει ελεγμένη παρουσία. Απορρίπτει μη HTTPS διευθύνσεις, ονόματα που δεν ταιριάζουν σε δηλωμένο επίθημα, αποκρίσεις που δεν είναι εικόνες και υπερβολικά μεγάλα αρχεία.

Τα τελικά σημεία είναι δημόσια και χωρίς έλεγχο ταυτότητας (οι παρουσίες τα καλούν απευθείας από το πρόγραμμα περιήγησης, οπότε δεν υπάρχει μυστικό προς αποστολή) και μοιράζονται το γενικό όριο αιτημάτων του API· δεν υπάρχει ξεχωριστό όριο ανά παρουσία. Μη χρησιμοποιείτε τον proxy για ιδιωτικό περιεχόμενο λογαριασμών, πόρους με έλεγχο ταυτότητας, URL παρακολούθησης, αυθαίρετα δεδομένα χρήστη ή περιεχόμενο που δεν είναι εικόνα.