Skip to main content

Social

It is common for entertainment apps and games to include social features for interactions between players. Each user on Jest can set up their profile with a username and a customizable avatar. This is an optional feature and some users may not have a profile yet and guest users will not have one. You should always account for that, and use reasonable fallbacks for displaying player info in your app.

For player identity and registration state, see Player.

User profile​

After the SDK is initialized, you can get the current user's profile. See SDK initialization for HTML5 or Unity for more information.

The method will work for both registered and guest users. For guest players or players who haven't set their profile up yet, the profile or parts of it will be null.

Placeholder avatar

The placeholder avatar.

To ensure a good experience for users, the requested avatar can be 64x64, 128x128, 256x256, 512x512, or 1000x1000 pixels. Use the size that best fits your UI for the least amount of network traffic and the best visual quality.

Get the profile​

JestSDK.social.getProfile(options?)

Calling getProfile() before the SDK is initialized throws an error.

function exampleGetProfile() {
  const profile = JestSDK.social.getProfile();

  return {
    username: profile?.username ?? "You",
    avatarUrl:
      profile?.avatarUrl ??
      "https://jest.com/public/avatar/avatar-placeholder.webp",
  };
}

Pass avatarSize to request a specific avatar size:

JestSDK.social.getProfile({ avatarSize: 128 });
getProfile(options?: {
  avatarSize: 64 | 128 | 256 | 512 | 1000
}): {
  username: string;
  avatarUrl: string | null;
} | null;

Options:

NameTypeDescription
avatarSize64 | 128 | 256 | 512 | 1000The size of the avatar to fetch. Defaults to 1000.

Returns:

NameTypeDescription
usernamestringThe username of the currently logged in user.
avatarUrlstring | nullThe URL of the avatar of the currently logged in user.

Bots​

When apps need to fill in some user slots with bots, we recommend using bot avatars. There are 1000 unique bot avatars, enough to ensure that it's unlikely for two usernames to have the same avatar. They are generated deterministically, so the same username will always return the same avatar.

The avatar sizes are the same as for player avatars: 64x64, 128x128, 256x256, 512x512, and 1000x1000 pixels. It is recommended to request the smallest size that fits your UI for the best performance, as this will minimize network traffic and improve loading times.

512x512256x256128x12864x64

The mapping from username to avatar is deterministic and identical across game engines, so the same username yields the same avatar whether your app uses the Unity, Godot, or HTML5 SDK.

Get a bot avatar​

JestSDK.social.getBotAvatar(opts)

function getBots(usernames: string[]) {
  const avatars = [];

  for (const username of usernames) {
    avatars.push({
      username,
      avatar: JestSDK.social.getBotAvatar({ username, size: 128 }),
    });
  }

  return avatars;
}

getBots(["Hello", "Jest", "Bots"]);
getBotAvatar(
  opts: {
    username: string;
    size?: 64 | 128 | 256 | 512 | 1000;
  }
): string;

Options:

NameTypeDescription
usernamestringRequired. The username of the bot.
size64 | 128 | 256 | 512 | 1000Optional. The size of the avatar. Defaults to 1000.

Returns:

TypeDescription
stringThe URL of the bot avatar.

Custom screenshots​

The platform can ask your app for a screenshot. Players trigger this with the camera button in the Jest footer, then caption the capture and post it to chat, share it to another app, or download it.

Register a screenshot provider​

JestSDK.social.setScreenshotProvider(provider)

By default the SDK captures your app's main canvas automatically, which works for most apps. If automatic capture doesn't produce good results (or you want control over what's shown), register a custom screenshot provider:

JestSDK.social.setScreenshotProvider(() => {
  // Return the screenshot as a base64-encoded PNG. Both raw base64 and
  // data URLs (e.g. from canvas.toDataURL("image/png")) are accepted.
  return myRenderer.captureFrameAsBase64Png();
});

Return null when no screenshot is available — for example while the game is still loading, or on a screen you don't want captured:

JestSDK.social.setScreenshotProvider(() => {
  if (game.state !== "playing") {
    return null;
  }
  return game.captureScreenshot();
});

Providers may be async. Pass null to setScreenshotProvider to unregister your provider and restore the SDK's automatic canvas capture.

To preview a capture locally, open the JestSDK debug menu, expand Screenshots (collapsed by default), and click Capture Screenshot. See Test screenshot capture.

setScreenshotProvider(
  provider: (() => string | null | Promise<string | null>) | null
): void;

Options:

NameTypeDescription
providerfunction | nullRequired. Called when the platform requests a screenshot. Return a base64 PNG (raw or data URL), or null when no screenshot is available. Pass null to restore automatic capture.

Sharing images​

Share an image​

JestSDK.social.shareImage(options?)

Opens the platform's share sheet for an image — the same sheet the platform's own screenshot button shows, offering chat, the native share sheet and download. Use it behind your own button: a "share my build", "brag about this score" or "send a coupon" action.

await JestSDK.social.shareImage({
  image: couponCanvas.toDataURL("image/png"),
  entryPayload: { coupon: "SPRING25" },
});

The player picks where it goes and writes the caption themselves, so your app never shares on their behalf without a tap. Every call opens the same sheet the footer's screenshot button shows:

const { canceled } = await JestSDK.social.shareImage();
if (!canceled) {
  game.onImageShared();
}

Omit image and the platform captures your app's canvas, or your registered screenshot provider, the same way the platform's own screenshot button does.

When you pass an entryPayload, the platform appends a link to your app to the posted message. Opening that link launches your app with the payload in the entry payload, so a code or coupon travels with the share and is redeemable from chat.

canceled is false only when the image was posted to chat. A share to another app, a download, or a dismissed sheet all report canceled: true. A failed post is reported to the player in the sheet; the promise rejects only when the image is rejected or capture fails before the sheet opens.

canceled: true is not proof that nothing was posted: a player who leaves the page while a post is still landing is reported as cancelled even though the message arrives. Re-sharing on canceled can duplicate the message.

shareImage(options?: {
  image?: string;
  entryPayload?: Record<string, unknown>;
}): Promise<{ canceled: boolean }>;

Options:

NameTypeDescription
imagestringOptional. Base64 PNG, raw or as a data URL, at most 2 MB. Omit it to let the platform capture your canvas.
entryPayloadobjectOptional. Handed back to your app when a player opens the shared message. The platform appends a link carrying it to the post.