Install and test the Freebee Player app

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; 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 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. 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:

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.

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.