Guides

Overriding Device URLs

Suggest Edits

In normal operations, every device connects to the tenant's application URL when it starts up, or the user presses the home button on the remote control. But there may be some situations in which you want to route traffic from individual devices to different application URLs:

  • During development, you may want to work on an app without affecting other devices.
  • In production, you may want to control which users see which versions of your app.

While Senza does not provide the capability to override the URL for a device out of the box, there are a number of ways that you can override the device URL yourself:

  1. Using a JavaScript script (client side)
  2. Using a PHP script (server side)
  3. Using an NGINX reverse proxy

In all cases we will create an index that maps a set of device IDs to some custom URLs. We will look up the device ID from the request headers or device info, check if the device has a custom URL, and then redirect the user to that link or the default one if the device is not listed.

These approaches are useful if you want to permanently override the URL for a device. If you just want to override the URL on a temporary basis, you can enable override the URL in the simulator or use the debugger to change the URL. See Setting the URL for more details.

JavaScript

You can set the application URL of the tenant to a faceless script that will check the device ID using the client library, check if there is an override URL available for the device, and then redirect to that or the default URL. For simplicity we can embed the script in a single HTML file, and load the client library from the CDN. 

<!DOCTYPE html>
<html>
<head>
  <title>Senza</title>
</head>
<body></body>
<script src="https://senza-sdk.streaming.synamedia.com/latest/bundle.js"></script>
<script>
  let defaultUrl = "https://senzadev.net/about/";
  let deviceUrls = {
    "06fffbeb0d21af04": "https://senzadev.net/banner/",
    "7e6d37c30d21af04": "https://senzadev.net/zoom/",
  };
  
  window.addEventListener("load", async () => {
    try {
      await senza.init();
      
      let deviceId = senza?.deviceManager?.deviceInfo?.deviceId;
      let redirectUrl = deviceUrls[deviceId] || defaultUrl;
      
      window.location = redirectUrl;
    } catch (error) {
      window.location = defaultUrl;
    }
  });
</script>
</html>

We will specify a defaultUrl that most users will see, and a deviceUrls object that maps device IDs to custom URLs. When the window loads and the client library is ready, we'll use the deviceManager to get the device ID, and then check if there is a URL override for the device.

Then we'll set the window location to the correct URL. If anything goes wrong, we'll catch the error and go to the default URL. This will all happen quickly, so we won't display anything on the page.

PHP script

A slightly different approach is to run a PHP script to do the same thing. In this case the script runs server-side, so it may be somewhat faster and more secure. It has the advantage over NGINX that you don't need to install any additional software or modify your web server's configuration, other than enabling PHP .

<?php

$defaultUrl = "https://andrewzc.net/about/";
$deviceUrls = [
    "06fffbeb0d21af04" => "https://andrewzc.net/banner/",
    "7e6d37c30d21af04" => "https://andrewzc.net/zoom/",
];

$key = "HTTP_X_HYPERSCALE_DEVICEID";
$deviceId = isset($_SERVER[$key]) ? $_SERVER[$key] : null;
$redirectURL = array_key_exists($deviceId, $deviceUrls) ? $deviceUrls[$deviceId] : $defaultUrl;

header("Location: $redirectURL");
exit;

?>

First, we'll define a $defaultUrl variable with the default URL, and a $deviceUrls array with our map of device IDs to URLs.

We'll take advantage of the fact that all requests from the Senza platform to your web server have the device ID included in the HTTP-X-Hyperscale-DeviceID request header. We'll look up the device ID from the $_SERVER array, which has all the request headers (note that the keys are uppercase).

Then we'll check if there is a custom URL for this device, otherwise using the default URL. Then we'll return a response to the browser with a header that specifies the new location, and it will redirect to that URL.

NGINX reverse proxy

Finally, we can use NGINX as a reverse proxy, which sits in front of your web server and routes traffic based on a variety of criteria. Learn more about configuring NGINX as a reverse proxy.

By default, NGINX creates variables for each request header. Note the slight difference in punctuation and capitalization: if the header is HTTP-X-Hyperscale-DeviceID, the variable will be $http_x_hyperscale_deviceid (dollar sign, lowercase, hyphens to underscores).

map $http_x_hyperscale_deviceid $device_url {
  default https://andrewzc.net/about/; 
  06fffbeb0d21af04 https://andrewzc.net/banner/;
  7e6d37c30d21af04 https://andrewzc.net/zoom/;
}

proxy_pass $device_url

We will use the map function which is like a switch statement that checks the value of the header, looks up the key in the map, and sets the $device_url variable to the correct value, falling back to the default value if the key is not found. You can tell that NGINX was built for this.

Then we call the proxy_pass directive with the device URL to redirect to the correct page.

Updated 4 months ago

What’s Next