Customize the thumbnail image

The Koji platform renders a thumbnail (Open Graph) image based on a screenshot of the app. By default, the platform takes a screenshot of the initial view.

To improve the sharing experience, you can render a custom view of your app that is designed specifically to make an impression when sharing it. You can also control the timing of the screenshot to ensure that all relevant assets have loaded before the image is generated.

About custom metadata

If you were designing a web app from scratch, you would customize the Open Graph metadata to specify what gets displayed when the app is shared. The Open Graph metadata consists of meta tags, such as og:image, og:title, and og:description. The thumbnail corresponds to the og:image.

The Koji platform automatically sets all the meta tags for you, but you can override some of Koji’s default settings to provide a customized sharing experience.

Tip	In addition to the thumbnail image, you can give creators the ability to customize the `og:title` and `og:description` by enabling the custom metadata entitlement.

Rendering a custom view for the screenshot

In some cases, the initial view might not be the best thumbnail image for your app. For example, if a game starts with an instruction screen, a screenshot of the first level might provide a better preview.

To customize the thumbnail for your app, use Koji.playerState.context in the @withkoji/core package to render a custom view for the screenshot context. For optimal thumbnail support, design this view with the following considerations in mind.

The image is responsive.
The image looks good with a square aspect ratio.
The image is optimized for faster loading. For example, to reduce the image size to 400x400 pixels and load only the first frame of a gif, you can add query parameters at the end of your image’s URL: https://images.koji-cdn.com/path/to/myimage.gif?fit=bounds&width=400&height=400&frame=1
The image includes customizable elements to generate unique previews for each customized version of the app.

For the following example, assume the app supports customizing the title and logo values.

In your application code, add a conditional statement to display a custom view for the screenshot context. For example:

...
const remixValues = Koji.remix.get();
...
if (Koji.playerState.context === 'screenshot') {
  return (
    <SocialSharePreview>
      <h1>{remixValues.title}</h1>
      <img src={optimizeScreenshot(remixValues.logo)} />
    </SocialSharePreview>
  );
}
// If the context is not equal to 'screenshot', return the HTML for the relevant context.
...

Define appropriate styles for the thumbnail image.

To ensure that it is displayed correctly, design the thumbnail image as a responsive square.

const SocialSharePreview = styled.div`
  background-color: #395b88;
  min-height: 100vh;
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  font-size: calc(10px + 2vmin);
  text-align: center;
  color: #fcfcfc;
`;

Test the custom thumbnail image and make adjustments, as necessary.
- In the Koji code editor, select More › Thumbnail in the preview pane.
- In the Koji debugger, update the session settings to point to your development environment, and select Thumbnail.

Controlling the screenshot timing

The Koji platform uses the window.kojiScreenshotReady property to determine the timing of the thumbnail screenshot.

When the platform loads an app, it checks for window.kojiScreenshotReady = false;. If this value isn’t present, the platform takes the screenshot right away. If it is, the platform sets an interval to check the value every 100ms. When the value changes to true or a maximum interval of 2000ms elapses, the platform takes the screenshot.

This feature enables you to ensure that the relevant fonts, images, videos, and other assets have loaded before the thumbnail is generated. For example:

In the index.html file, add the following script tag.

<script> window.kojiScreenshotReady = false; </script>

In your application code, add the following code after confirming that the relevant assets have loaded.
```
window.kojiScreenshotReady = true;
```