> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add the web reader player to your site

> Copy the web reader embed snippet, paste it into your article template inline or floating, override settings on one page, and use it on single-page sites.

> [!NOTE]
>
> Web reader is in beta and switched on for selected accounts.

The snippet is a small piece of HTML that puts the player on your articles. You paste it once into the template your articles use, and every article gets the player. It carries the site's ID and the settings you saved, so copy it again after you change appearance or readings.

## Before you start

* Set up the site and give every reading a voice. See [Set up a site](https://docs.tryhamsa.com/media/web-reader/set-up-a-site.md).
* You need to be able to edit your site's article template, or ask your developer to.

## Copy the snippet

**1. Open the site's Setup tab**

In **Web reader**, open the site and go to **Setup**.

**2. Choose how it is installed**

Under **How it is installed**, choose **Floating** or **Inline**. The choice changes the snippet below it and isn't saved, so you can install the player differently on different pages.

**3. Copy it**

Click **Copy snippet** in the **Getting this live** checklist, or copy the snippet card. **Copy embed code** at the top of the site page and in the site's menu in the list copies the floating version.

![How it is installed set to Inline, the embed snippet for it, and the Overriding on one page table](https://mintcdn.com/hamsa-452fa79a/SjdNHyLOJ-5kYaqE/images/media/web-reader/snippet-inline-light.webp?fit=max\&auto=format\&n=SjdNHyLOJ-5kYaqE\&q=85\&s=1da32fd8904a36f8c4780b1416e055d9)

This is the snippet for a new site with an English reading, as the app gives it:

```html theme={null}
<!-- Hamsa Web Reader -->
<div
  hamsa-webreader
  data-projectid="YOUR_SITE_ID"
  data-placement="floating"
  data-theme="dark"
  data-language="EN"
  data-ui-language="en"
></div>
<script src="https://media.tryhamsa.com/webreader.js" async></script>
```

`data-projectid` is your site ID, shown under the domain on the site page. The other attributes depend on your settings: `data-languages` appears when you offer more than one reading, `data-accent` when you changed the accent colour, `data-label` when you changed the launcher label.

## Inline or floating

| Placement | What readers see | Where to put the snippet |
| - | - | - |
| **Floating** | A small button fixed to the bottom corner of the page, over the article. Tapping it opens the player. Escape closes it. | Anywhere in the page. The position of the tag doesn't matter. |
| **Inline** | The player itself, in the page flow, already open. | Exactly where the player should appear, usually under the article heading. |

The floating button sits 24 pixels from the bottom corner, on the right on left-to-right pages and on the left on right-to-left pages.

## Paste it into your site

**1. Open your article template**

Use the template every article is built from, not a single article, so one change covers them all.

**2. Paste the snippet**

For inline, paste it where the player should show, for example right after the headline. For floating, paste it anywhere inside `<body>`.

**3. Publish and test**

Open a published article and press play. The first play converts the article, and it shows on the site's **Conversions** tab. The **Getting this live** checklist then shows **Live**.

Put one snippet on a page. If there are several, only the first is used.

The page must be on the site's domain or one of its subdomains. On any other domain the player shows "Domain not authorized".

## Override settings on one page

The snippet carries your saved settings. To make one page differ, change or add an attribute on that page's snippet by hand. The **Overriding on one page** card under the snippet lists them.

| Setting | Attribute | Example |
| - | - | - |
| **Widget language** | `data-ui-language` | `ar` or `en` |
| **Played first** | `data-language` | `EGY` (a reading the site offers) |
| **Theme** | `data-theme` | `light` or `dark` |
| **Accent colour** | `data-accent` | `#FF6B00` |
| **Placement** | `data-placement` | `inline` or `floating` |
| **Button label** | `data-label` | `استمع للمقال` |
| **Custom CSS** | `data-custom-css` | `.wr-card { --wr-radius: 8px; }` |
| **Layout** | `data-layout` | `default`, `compact`, `minimal`, `floating` or `expanded` |
| **Maximum width** | `data-max-width` | `700px` |

The player also reads these attributes:

| Attribute | Values |
| - | - |
| `data-width` | `auto`, `full`, or a width such as `600px` |
| `data-height` | `auto`, or a height such as `120px` |
| `data-min-height` | A height such as `80px` |
| `data-align` | `left`, `center` or `right` |
| `data-bg`, `data-text` | Background and text colours as `#RRGGBB`, used when there is no `data-theme` |
| `data-label-playing` | The launcher's wording while audio plays (default "Playing article") |
| `data-auto-open` | `true` opens the floating player when the page loads |

An attribute on the page always wins over the site's saved setting. Longer custom CSS can go in a `<style type="text/hamsa-player">` element inside the `<div>` instead of `data-custom-css`.

```html theme={null}
<div
  hamsa-webreader
  data-projectid="YOUR_SITE_ID"
  data-placement="inline"
  data-layout="compact"
  data-max-width="700px"
>
  <style type="text/hamsa-player">
    .wr-card { --wr-radius: 4px; --wr-shadow: none; }
  </style>
</div>
<script src="https://media.tryhamsa.com/webreader.js" async></script>
```

## Single-page sites

The player follows page changes on sites built as single-page apps: when the address changes, it resets for the new article. If your app adds the `<div hamsa-webreader>` after the script has loaded, the player finds it on its own. You can also call `window.__hamsaWebReaderMount()` once the container is on the page.

## What readers see when something is wrong

| Message | Why |
| - | - |
| "Domain not authorized" | The page isn't on the site's domain or its subdomains. |
| "Language not configured" | The page asks for a reading the site doesn't offer, for example a `data-language` you removed. |
| "Article too short" / "Article too long" | The article has fewer than 50 or more than 10,000 words. |
| "No content found" | No article text could be found on the page. |
| "Could not fetch page" | Hamsa couldn't load the page from your site. |
| "Page too large" / "Too many redirects" | The page is over 5 MB, or redirects more than 5 times. |
| "Not enough credit" | The account has run out of credits. |

## Good to know

* The snippet doesn't need an API key. The site ID is public in your page source; only pages on your domain can use it.
* After you save new readings, theme, colours, accent, widget language or launcher label, copy the snippet again and replace it on your site. Voices and dictionaries apply without a new snippet.
* While the site is inactive, the player plays nothing on any page.

## Related

> [card] [Player appearance](https://docs.tryhamsa.com/media/web-reader/appearance.md)
>
> Layouts, sizes and custom CSS.

> [card] [Conversions and chunks](https://docs.tryhamsa.com/media/web-reader/conversions.md)
>
> Check the articles readers have played.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.