Getting started

SDK Overview

Explore the SDK's capabilities, package exports, supported frameworks, and core functionality.

PresenceKit SDK

typescriptjavascriptreactvue

@iconical/presence is a browser-safe TypeScript SDK for showing opted-in Discord presence on websites. It combines REST snapshots, real-time subscriptions, helper functions and optional framework adapters.

What is included?

Feature	Use it for
REST snapshots	Read a user's latest approved profile, status and activities
Live subscriptions	Update a page when Discord presence changes
Automatic transport fallback	Continue updating through REST polling when SSE cannot be used
Multi-user methods	Show a small team, roster or contributor list
Shared connection manager	Reuse a browser-tab connection across independent widgets
Spotify and artwork helpers	Display track details, game imagery and reliable fallback tiles
React, Vue, Svelte adapters	Integrate with framework state and lifecycle handling
React UI components	Render ready-made status, team and Spotify cards

Package entrypoints

// Framework-independent SDK and helpers
import { createPresenceClient } from "@iconical/presence";

// React hooks and React components (in React projects)
import { usePresence } from "@iconical/presence/react";
import { LivePresenceCard } from "@iconical/presence/react-ui";

// Other framework adapters
// import { usePresence } from "@iconical/presence/vue";
// import { createPresenceStore } from "@iconical/presence/svelte";

Only import the adapter appropriate for your application. The core SDK does not require React, Vue or Svelte.

A minimal client

import { createPresenceClient } from "@iconical/presence";

const client = createPresenceClient();
const result = await client.getPresence("123456789012345678");

console.log(result.profile.displayName);
console.log(result.availability);
console.log(result.presence?.activities ?? []);

Snapshot and live updates

graph TD
  A[Website] --> B{Needed once or continuously?}
  B -->|Once| C[getPresence]
  B -->|Live| D[subscribePresence]
  D --> E[SSE or REST polling]
  C --> F[Render approved data]
  E --> F

Snapshots versus subscriptions

A snapshot is a single getPresence() request; use it for on-demand displays or one-time server-side rendering. A subscription uses subscribePresence() and delivers changes over time; use it on interactive web pages and unsubscribe when the view is removed.

Framework adapters handle cleanup for you. For many presence cards on one page, use the [shared connection manager](./shared-connections.md) or the adapters, which share underlying connections.

Useful exports

createPresenceClient() — get a low-level client with getPresence, subscribePresence, getPresences, and subscribePresences.
getSharedPresenceClient() — reuse subscriptions across UI widgets.
createPresenceConnectionManager() — create an independently managed group of subscriptions.
getSpotifyActivity() and getSpotifyNowPlaying() — inspect current Spotify presence.
getPlayingActivities() and getCustomStatus() — filter activities.
getActivityArtwork() and getActivityElapsedMs() — build richer activity cards.
PresenceKitError — inspect SDK HTTP errors through .status and .code.

Consent and data limits

PresenceKit cannot search all Discord users, expose unconfirmed members, or provide a history of their activity. The public API checks opt-in approval, and the SDK only receives approved, current data. Missing or revoked records should be displayed as unavailable rather than guessed.

The API origin is fixed at https://presence-api.iconical.dev. Consumers do not configure a Discord bot or provide credentials to the SDK.

Choose your next guide

Start with [Getting started](./getting-started.md) for a tutorial, [API reference](./api-reference.md) for full method signatures, or [Framework integrations](./README.md#framework-integrations) for runnable examples.

Was this page helpful?

Installation