Presence API

Verwende die Nowly-Presence-API, um Discord Rich Presence aus einer Website-Integration zu aktualisieren.

Eine Presence erstellen

Presence ist ein globales Objekt, das von der Nowly-Laufzeitumgebung bereitgestellt wird - du musst es nicht importieren.

Jede Presence beginnt mit einer Presence-Instanz:

const presence = new Presence()

UpdateData-Ereignis

Verwende UpdateData, um die Aktivität zu aktualisieren:

presence.on("UpdateData", async () => {
  await presence.setActivity({
    details: "Watching a video",
  })
})

setActivity

setActivity sendet die aktuelle Discord-Aktivität. Häufig verwendete Felder sind:

Feld	Typ	Beschreibung	Standard
`detailsUrl`	string	Optionaler öffentlicher HTTPS-Link für details (SDK 1.7.0+).	-
`stateUrl`	string	Optionaler öffentlicher HTTPS-Link für state (SDK 1.7.0+).	-
`name`	string	Optionaler Aktivitätsname. Standardmäßig wird der Name der Präsenz verwendet.	-
`statusDisplayType`	0 \| 1 \| 2	Feld im kompakten Discord-Status: 0 = name (Standard), 1 = state, 2 = details.	-
`details`	string	Primäre Aktivitätszeile, die in Discord angezeigt wird.	-
`state`	string	Sekundäre Aktivitätszeile, angezeigt unter details.	-
`startTimestamp`	number	Unix-Zeitstempel für den verstrichenen Aktivitätsfortschritt.	-
`endTimestamp`	number	Unix-Zeitstempel für den verbleibenden Aktivitätsfortschritt.	-
`largeImageKey`	string	Haupt-Bild-Asset-Schlüssel, meist Assets.Logo oder Assets.Thumbnail (Globals der Laufzeitumgebung).	-
`largeImageText`	string	Tooltip für das große Bild.	-
`smallImageKey`	string	Optionaler Schlüssel für ein kleines Bild-Asset.	-
`smallImageText`	string	Tooltip für das kleine Bild.	-
`type`	number	Discord-Aktivitätstyp aus PresenceType.	-
`buttons`	array	Optionale Discord-Activity-Buttons.	-

Discord lehnt Rich-Presence-Payloads ab, wenn largeImageText oder smallImageText weniger als zwei Zeichen enthält. Nowly bereinigt diese optionalen Tooltips und lässt sie weg, wenn das Ergebnis kürzer als zwei Zeichen ist; das Bild bleibt verfügbar.

detailsUrl / stateUrl

SDK 1.7.0+ ergänzt die optionalen Textfelder detailsUrl und stateUrl, die die jeweilige Aktivitätszeile unabhängig von Schaltflächen verlinken. Erweiterung und nativer Host müssen beide Felder unterstützen; ältere Versionen ignorieren sie. Der Aktivitätsname bleibt unverändert.

Verwende überprüfte öffentliche HTTPS-URLs ohne Zugangsdaten und mit höchstens 2048 Zeichen. Links ohne zugehörigen Text oder mit ungültigen URLs werden weggelassen. Inhaltskennungen wie YouTubes Parameter v bleiben erhalten. Teile niemals Zugriffstoken, private Chats, geheime Links oder durch Datenschutzeinstellungen ausgeblendete Informationen. Unbekannte Ziele werden nicht verlinkt.

await presence.setActivity({
  details: "Videotitel",
  detailsUrl: "https://www.youtube.com/watch?v=VIDEO_ID",
  state: "Kanalname",
  stateUrl: "https://www.youtube.com/@channel",
})

statusDisplayType

statusDisplayType wählt den Text im kompakten Discord-Status. Name, Details und Status der Aktivitätskarte bleiben unverändert.

0 (Standard): name
1: state
2: details

Zum Beispiel den Videotitel im kompakten Status anzeigen und den Aktivitätsnamen sowie den Kanal in der Karte beibehalten:

await presence.setActivity({
  name: "Videodienst",
  details: "Videotitel",
  state: "Kanalname",
  statusDisplayType: 2,
})

Verwende eine SDK-Version, die dieses Feld enthält, und aktualisiere die Nowly-Erweiterung sowie den nativen Host. Ältere Runtime-Versionen ignorieren das Feld und behalten die Standardanzeige bei.

clearActivity

Rufe clearActivity auf, wenn es nichts Sehenswertes gibt:

presence.clearActivity()

PresenceType

PresenceType ist ein benannter Export aus @nowly/sdk:

import { PresenceType } from "@nowly/sdk"

Er bildet Discord-Aktivitätstypen ab: Playing, Streaming, Listening, Watching und Competing.

getSetting

Lese eine typisierte Presence-Einstellung nach Presence.Settings. Der Wert ist die gespeicherte Einstellung des Nutzers oder der Standardwert aus der Definition:

const showButtons = await presence.getSetting<boolean>("showButtons")

UpdateData erhält ebenfalls ctx.settings mit derselben Map. Beide aktualisieren sich, wenn der Nutzer Einstellungen im Seitenpanel ändert.

Logging

Verwende presence.info und presence.error für Debug-Meldungen während der Entwicklung.

Auf GitHub bearbeiten

Command Palette