# Install and test the Freebee Player app

Last updated Oct 28, 2026 · Page: https://freebeeads.com/docs/repo/player-install · Markdown: https://freebeeads.com/docs/md/repo/player-install.md · All docs: https://freebeeads.com/llms-full.txt

This guide is for the ops person who sets up the box behind a mall screen. It covers Android,
Windows and Mac: how to install the app, pair the box, check it on the Devices page, and run the
five tests we do before a screen goes live (camera walk-past, wifi cut, power cut, a test message,
a restart). No technical background needed. Allow about 30 minutes per box the first time.

Freebee Player is a small app that opens the Freebee ad loop full screen, starts by itself when
the box powers on, keeps playing through wifi cuts, and reports the box's health (temperature,
memory, disk space, crashes) to the Devices page. The older way, a browser tab on `/player`, still
works and is described in [Player setup](/docs/repo/player-setup); the app replaces the kiosk tricks
in that guide.

## Before you start

You need:

- The box, connected to the screen, with a keyboard and mouse plugged in for setup.
- The mall's wifi name and password, or a network cable.
- A phone or laptop signed in to the ops portal (ops@ account) to pair the box and watch the
  Devices page.
- For the camera tests: the USB camera mounted where it will stay, at about head height and
  aimed along the walkway (the "Camera placement" section of `docs/AUDIENCE_MEASUREMENT.md` has
  the details).

## Which download

Open **freebeeads.com/download** on the box itself. There are three cards:

- **Android**: Android TV boxes, signage boxes and kiosk tablets.
- **Windows**: mini PCs (Intel N100 or similar).
- **Mac**: a Mac mini.

Each card shows the version, the file size and a SHA-256 checksum. The checksum is a fingerprint
of the file; you only need it if our team asks you to confirm the file is complete. If a card says
**Not published yet**, that version is not ready; use a browser player for now and tell our team.

## Android

1. On the box, open the browser, go to freebeeads.com/download and press **Download for Android**.
2. Open the downloaded file (from the notification, or the Downloads app). Android asks whether
   this browser may install apps: choose **Settings**, switch on **Allow from this source**, go back
   and press **Install**.
3. Open **Freebee Player**. If this screen counts its audience, press **Allow** when it asks for the
   camera.
4. The screen shows a large 6-character code. Pair it (see "Pair the box" below).
5. Check the box on the Devices page (see "What to check on the Devices page").

For a box that must never show the Android home screen (kiosk mode), our team sets the box up as
the app's own device once, with a laptop; ask before the install day. Without it the app still
starts on boot and comes back by itself after a crash.

## Windows

1. On the mini PC, open the browser, go to freebeeads.com/download and press
   **Download for Windows**.
2. Run the downloaded installer. If Windows shows "Windows protected your PC", press
   **More info**, then **Run anyway**.
3. The installer finishes and the player opens full screen. From now on it starts with Windows.
4. The screen shows a large 6-character code. Pair it (see "Pair the box" below).
5. Check the box on the Devices page.

Set the box to sign in by itself and never sleep, so the player comes back after a power cut:
steps 1 to 3 of the Windows section in [Player setup](/docs/repo/player-setup) do this. To get out
of the full-screen player on site, open Task Manager (Ctrl+Shift+Esc) and end **Freebee Player**;
closing its window with Alt+F4 only makes it reopen. It comes back on the next restart.

## Mac

1. On the Mac, open the browser, go to freebeeads.com/download and press **Download for Mac**.
2. Open the downloaded file and drag **Freebee Player** into **Applications**.
3. Open Applications and double click **Freebee Player**. The first time, macOS says it cannot
   check the app: open **System Settings > Privacy & Security**, scroll down and press
   **Open Anyway**, then open the app again (this is needed until our Mac build is signed).
   Press **OK** when it asks for the camera.
4. The screen shows a large 6-character code. Pair it.
5. Check the box on the Devices page.

Set the Mac to sign in by itself and restart after a power cut: step 1 and 2 of the Mac section
in [Player setup](/docs/repo/player-setup). To get out of the player on site, press Cmd+Q; once
auto-start is set up it comes back by itself after about 5 seconds, so do what you need quickly or
turn auto-start off first (see Player setup).

## Pair the box

1. On your phone or laptop open the ops portal, go to **Devices** and press **Pair a device**.
2. Type the 6-character code from the screen and pick the screen this box drives.
3. Within a minute the ads start on the screen. The code refreshes by itself if it expires, so
   there is no rush; just type the new one.

## What to check on the Devices page

Open **Devices**. The strip at the top counts every box ("12 boxes · 11 online · 1 hot"). Find the
card for your screen and check:

- **Last check-in** has a green dot. Boxes check in every 15 seconds.
- **Runs on** says Android, Windows or Mac (not Browser).
- **App** shows the same version as the download page.
- **Temperature**, **CPU** and **Disk free** show numbers. A browser player cannot report these;
  the app can (temperature is not available on every box).
- **Crashes in 24 h** is 0.
- No alert chips, or only **Rebooted** if you just restarted it.

Press **Open box page** for the full view: alerts with what to do, four 24-hour charts (CPU,
memory, temperature, disk free), the buttons to fix things remotely, and the command and crash
history. The page refreshes itself every 15 seconds.

What the alerts mean, in short:

| Alert | What it means | What to do |
| --- | --- | --- |
| Offline | No check-in for 2 minutes or more | Check wifi or cable, then power. The screen keeps playing from its cache. |
| Running hot | The box reports a high temperature | Check airflow: nothing on top, vents clear. If it stays above 75°C for an hour, swap it. |
| Keeps crashing | The app crashed several times in 24 h | Press Restart app. If it crashes again within the hour, send the log to our team. |
| Keeps rebooting | Several restarts in a short time | Check the power adapter and the socket. |
| Disk almost full | Little storage left | Press Clear cache. If it fills again, the box is too small. |
| Low memory | Memory nearly used up | Press Restart app. If it comes back daily, use a bigger box. |
| Working hard | CPU high for a long time | Switch the camera to Faces mode, or Restart app. |
| Camera blocked | The player cannot use the camera | Allow the camera for Freebee Player on the box. |
| Old version | An older app than the download page | Install the latest app; pairing is kept. |
| Rebooted | The box restarted recently | Nothing, if you expected it. |

## Test 1: walk-past camera test

Only for screens that count their audience.

1. Close Freebee Player on the box (Windows: end it in Task Manager; Mac: Cmd+Q, and turn
   auto-start off first if it keeps coming back; Android: the app switcher,
   swipe it away). Only one program can use the camera at a time.
2. In the box's browser open freebeeads.com/player/vision-test and allow the camera.
3. Walk past at a normal pace. A blue box marked "person" should follow you. Stop and look at the
   screen: a box around your face turns green after about a second.
4. At a busy hour press **Start walk-past test** and count, by hand, the people who walk past for
   the same 60 seconds. Type your count in **Your own count**. Within about 15% is good. If not,
   change the camera angle or height and test again.
5. Open Freebee Player again. On the Devices page the camera should read "counting people" at the
   next check-in.

The camera never sends pictures anywhere; only counts leave the box.

## Test 2: wifi cut

1. Note the time. Turn off the box's wifi (or unplug its network cable, or switch off the router
   it uses) for 5 minutes. Leave the screen on.
2. On the screen: ads keep playing as normal, from the box's cache.
3. On the Devices page: after about 30 seconds the last check-in dot turns amber, after 2 minutes
   red, and the card gets the **Offline** chip. The Today page lists it under alerts.
4. Turn the wifi back on. Within about 15 seconds the dot is green again and the chip goes away.
   The play records saved during the cut upload by themselves; nothing is counted twice.
5. On the box page, the charts show a grey band for the minutes the box was offline.

If the box does not come back within 2 minutes of the wifi returning, press **Reload** on the box
page, then check the wifi settings on the box.

## Test 3: power cut

1. Pull the box's power plug while an ad is playing. Wait 1 minute. Plug it back in.
2. The box starts, the app opens by itself and ads start again within about 2 minutes. You should
   **not** see a pairing code. If you do, the box lost its pairing: type the code into Pair a
   device and tell our team.
3. On the Devices page: the card shows the **Rebooted** chip and **Up since boot** a few minutes.
   The box page charts show a grey band for the time it was off.

If the box does not start by itself, its power setting is wrong: see "Restore on AC power loss"
(Windows) or `autorestart` (Mac) in [Player setup](/docs/repo/player-setup).

## Test 4: send a test message

1. On the box page, under **Send a message to the screen**, type a short line, for example
   "Testing screen B22, please ignore", choose how long to show it (15 seconds is fine) and press
   **Send message**.
2. Within about 15 seconds the text appears in large letters along the bottom of the screen. Ads
   keep playing above it. It disappears after the time you chose.
3. Under **Commands** on the box page the message shows "message shown for 15 s".

This is also the quickest way to be sure you are looking at the right box.

## Test 5: restart the app and reboot the box

1. On the box page press **Restart app**. It asks "Are you sure?"; press **Yes, restart app**.
   The screen goes dark for about 20 seconds and the ads come back. Under Commands it reads
   "restarting the app".
2. Press **Reboot box**, then **Yes, reboot box**. The screen goes dark for 1 to 3 minutes while the
   whole box restarts, then the ads come back. The card shows the **Rebooted** chip.

On a screen that runs in a browser instead of the app, Restart app reloads the page instead and
Reboot box answers "not supported in a browser". That is expected.

## When you are done

The box is ready when all five tests pass and the Devices card shows a green check-in, the right
platform, the latest app version, numbers for temperature, CPU and disk, and no alerts except
Rebooted. Unplug the keyboard and mouse.

## Updating the app

When the download page shows a newer version than the box, the card gets the **Old version** chip.
Download and install the new version over the old one, the same way as the first install. Pairing
and the play records waiting on the box are kept. The ad loop inside the app updates itself; only
the app needs this manual step.