How to embed an interactive image in your website

An .oim file is a normal PNG with texts, buttons and animations stored inside it. For those layers to work, the page has to load <oim-player>, the component that draws them. This guide follows the steps in the order you would do them.

Before you start

You need three things:

• An .oim.png file. You can use the sample on the CDN to test.
• A public URL where the file is hosted. The player downloads the file with fetch, so the server must allow your site (CORS). The demo CDN allows any origin.
• About five minutes.

There is one trap to know from the start. If you open the file directly in the browser, or put it in an <img> tag, you only see the base image. The texts and animations appear only when the player draws them.

Step 1: load the player

On a plain HTML page, one script tag is enough:

<script src="https://cdn.oim.media/player/v1/oim-player.js"></script>

Step 2: declare the image

Put the tag where you want the image to appear:

<oim-player
  src="https://cdn.oim.media/demo/imagen-muestra.oim.png"
  lang="en"
  mode="full"
  fit="contain"
  style="max-width: 800px; height: 600px; display: block; margin: 0 auto;">
</oim-player>

These are the attributes you will touch most:

• src: the URL of the file.
• lang: the starting language, for example en or es.
• mode="full": turns on animations and hover and click states. Without it the image stays still.
• fit: contain shows the whole image; cover fills the box and crops the edges.

Give the tag a width and a height, as in the example. The player uses the space you give it.

Step 3: choose the language

The file stores each text in several languages. To switch language from your page, call a method:

player.setLang('es');

Each change fires the oim:langchange event, in case your page needs to know.

Step 4: listen to what the user does

When someone presses an element with an action, the player fires oim:action. The file cannot send anyone anywhere by itself. It only announces the action. Your page decides what happens:

player.addEventListener('oim:action', (event) => {
  const { slot, name, trigger, targets } = event.detail;
  // If you want the click to navigate, the page decides the URL.
  if (name === 'Buy') {
    event.preventDefault();
    window.location.href = '/product/42';
  }
});

This way an ad can open your cart instead of an external site. If you do not listen to the event, nothing happens.

Step 5: use it in React

In React the element is used like any other tag. Install the package and import it once so the component is registered:

import '@oim/player-oim';

export function Banner() {
  return (
    <oim-player
      src="https://cdn.oim.media/demo/imagen-muestra.oim.png"
      lang="en"
      mode="full"
      fit="contain"
    />
  );
}

With React 18 or 19 and TypeScript, the guide adds a type declaration so the tag does not fail to compile. Copy it from the quick start guide.

Step 6: check the signature

Each signed file carries an ECDSA signature. To know its state, ask the player:

const status = player.getSecurityStatus(); // the signature state

If the signature does not match, the image is not shown. That makes sense: an altered file should not look authentic. For more on how the check works, read the integrity check in the security guide.

Settings for specific cases

Some attributes cover common situations:

• disable-animations="true": stops the loops. It respects the system's reduced motion preference.
• allow-zoom="true": lets the user zoom with the wheel or a pinch. Useful for diagrams.
• auto-rotate-lang="3000": switches language every three seconds.
• allow-lottie="false": skips loading Lottie animations, which saves memory in a grid of many images.

The accessibility guide explains how a screen reader reads the page, and what the file needs to describe. For the general use of each option, see also the player guide.

Frequently asked questions

Why do I only see the image, without the texts?

Almost always because the file is opened directly, or because the player script is missing. Check that the page loads oim-player.js without errors in the console, and that the src URL answers from your domain.

Do I need JavaScript to see the image?

To see the base image, no. An .oim is a valid PNG, and any viewer shows it. To see the texts, the languages and the animations, yes: you need the player, which is JavaScript.

Can I change a text without touching the image?

The text lives inside the file, not in the base image, so changing it does not force the pixels to be redrawn. But because the signature covers that data, editing the file by hand breaks the signature, so the file has to be signed again.

Does it work on a static site?

Yes. The plain HTML example needs no compiler and no framework. Serve the page and the .oim.png from your hosting, with the right CORS headers.

If you want to understand why the image can show that it was not altered, read the ECDSA signature on every pixel. To see what the player can do with micro-interactions, read vector micro-interactions without a framework.

For the background idea, that the text travels with the image, read the image that knows what it is.