Presence API

Nowly Presence APIを使って、ウェブサイト連携からDiscord Rich Presenceを更新します。

プレゼンスの作成

Presence はNowlyランタイムによって注入されるグローバルオブジェクトです。インポートする必要はありません。

すべてのプレゼンスは Presence インスタンスから始まります。

const presence = new Presence()

UpdateDataイベント

アクティビティを更新するには UpdateData を使用します。

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

setActivity

setActivity は現在のDiscordアクティビティを送信します。主なフィールドは以下のとおりです。

フィールド	タイプ	説明	デフォルト
`detailsUrl`	string	details 用の任意の公開 HTTPS リンク（SDK 1.7.0+）。	-
`stateUrl`	string	state 用の任意の公開 HTTPS リンク（SDK 1.7.0+）。	-
`name`	string	任意のアクティビティ名。省略時はプレゼンス名を使用します。	-
`statusDisplayType`	0 \| 1 \| 2	Discordのコンパクトなステータスに表示するフィールド。0 = name（既定）、1 = state、2 = details。	-
`details`	string	Discordに表示される主要なアクティビティ行。	-
`state`	string	detailsの下に表示される補助的なアクティビティ行。	-
`startTimestamp`	number	経過したアクティビティの進行状況を示すUnixタイムスタンプ。	-
`endTimestamp`	number	残りのアクティビティの進行状況を示すUnixタイムスタンプ。	-
`largeImageKey`	string	メイン画像アセットのキー。通常はAssets.LogoまたはAssets.Thumbnail(ランタイムが提供するグローバル変数)。	-
`largeImageText`	string	大きい画像のツールチップ。	-
`smallImageKey`	string	任意の小さい画像アセットのキー。	-
`smallImageText`	string	小さい画像のツールチップ。	-
`type`	number	PresenceTypeによるDiscordアクティビティの種類。	-
`buttons`	array	任意のDiscordアクティビティボタン。	-

Discord は、largeImageText または smallImageText が2文字未満の場合、Rich Presence ペイロードを拒否します。Nowly はこれらの任意のツールチップを整形し、結果が2文字未満の場合は省略します。画像自体は引き続き利用できます。

detailsUrl / stateUrl

SDK 1.7.0+ のオプション文字列フィールド detailsUrl と stateUrl は、ボタンとは独立して対応する活動行にリンクを付けます。拡張機能とネイティブホストの両方の対応が必要です。旧バージョンはこれらを無視し、活動名は変わりません。

認証情報を含まない、2048 文字以内の確認済み公開 HTTPS URL を使ってください。対応するテキストのないリンクや無効な URL は省略されます。YouTube の v などのコンテンツ識別子は保持できますが、アクセストークン、非公開チャット、秘密リンク、プライバシー設定で隠された情報は共有しないでください。リンク先が不明な場合は省略します。

await presence.setActivity({
  details: "動画タイトル",
  detailsUrl: "https://www.youtube.com/watch?v=VIDEO_ID",
  state: "チャンネル名",
  stateUrl: "https://www.youtube.com/@channel",
})

statusDisplayType

statusDisplayType はDiscordのコンパクトなステータスに表示するテキストを選びます。アクティビティカードの名前、詳細、状態は変更しません。

0（既定）: name
1: state
2: details

例えば、カード内のアクティビティ名とチャンネル名をそのまま残し、コンパクトなステータスには動画タイトルを表示できます。

await presence.setActivity({
  name: "動画サービス",
  details: "動画タイトル",
  state: "チャンネル名",
  statusDisplayType: 2,
})

このフィールドを含むSDKを使用し、Nowly拡張機能とネイティブホストの両方を更新してください。古いランタイムはこのフィールドを無視し、既定のステータス表示を維持します。

clearActivity

表示する価値のあるものがない場合は clearActivity を呼び出します。

presence.clearActivity()

PresenceType

PresenceType は @nowly/sdk からの名前付きエクスポートです。

import { PresenceType } from "@nowly/sdk"

これはDiscordのアクティビティタイプ(Playing、Streaming、Listening、Watching、Competing)に対応します。

getSetting

Presence.Settings に基づいた、型付けされたプレゼンス個別の設定を読み取ります。値はユーザーが保存した設定、または定義のデフォルト値です。

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

UpdateData も同じマップを持つ ctx.settings を受け取ります。ユーザーがサイドパネルで設定を変更すると、両方とも更新されます。

ロギング

開発中のデバッグメッセージには presence.info と presence.error を使用してください。

GitHubで編集

Command Palette