MKGeoComplyController - v1.0.0

MKGeoComplyController is a MKPlayer plugin that adds GeoComply BrowserGuard location verification support, gating playback of geo-restricted content behind a signed location JWT attached to the Azuki roll request.

Please follow the instructions on this page to understand how to properly add this plugin to MKPlayer.

Please note that this plugin is supported to work only with MediaKind registered source streams. This plugin depends on MKPlayer as its dependency and needs MKPlayer version 1.44.0 or newer for proper functioning. It also depends on the GeoComply BrowserGuard SDK (gc-html5.js), which your application must load separately via its own <script> tag (from GeoComply's own CDN) -- it is not bundled by this plugin.

Your application is also responsible for requesting the browser's geolocation permission (e.g. via navigator.geolocation.getCurrentPosition()) before enabling GeoComply -- this plugin never prompts the user for permission itself.

Getting started.

Install the plugin via NPM as below

npm install @mediakind/mkplayer-geocomply-plugin

Next include mkplayer-geocomply-plugin.js in the head of your HTML page along side mkplayer.js and GeoComply's own gc-html5.js:

<head>
    <title>My Video Player</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <!-- MKPlayer JavaScript and CSS along with MKGeoComplyController -->
    <script type="text/javascript" src="./node_modules/@mediakind/mkplayer/mkplayer.js"></script>
    <link rel="stylesheet" href="./node_modules/@mediakind/mkplayer/mkplayer-ui.css">
    <script type="text/javascript" src="https://<your-geocomply-cdn>/gc-html5.js"></script>
    <script type="text/javascript" src="./node_modules/@mediakind/mkplayer-geocomply-plugin/mkplayer-geocomply-plugin.js"></script>
</head>

Next, in your application import the plugin as below.

import { MKGeoComplyController, MKGeoComplyError, prepareGeoComplyAuthorization } from "@mediakind/mkplayer-geocomply-plugin";

As soon as your application knows the user wants GeoComply-gated content (e.g. a settings toggle), proactively run the authorize/verify chain -- this can happen before any player exists, so the location token is likely already cached by the time playback starts:

function onGeoComplyError(error) {
    console.warn(`GeoComply error: code: ${error.code}, message: ${error.message}`);
}

// environmentConfig is the same MKEnvironmentConfig object (authToken/ownerUid/
// serverUrl/kssUrl) you already use for the registered source itself.
await prepareGeoComplyAuthorization(environmentConfig, onGeoComplyError);

Initialize the plugin and attach it to your player as below:

// Initialize MKPlayer as before with video container and player config.
const player = new mkplayer.MKPlayer(videoContainer, playerConfig);

// Initialize MKGeoComplyController with the same environmentConfig and error callback.
const geoComplyController = new mkplayerGeocomplyPlugin.MKGeoComplyController(environmentConfig, onGeoComplyError);

// attachPlayer() (rather than passing the player into the constructor) is what
// lets one controller be attached to several players at once, e.g. a multiview grid.
geoComplyController.attachPlayer(player);

Replace your direct player.load(sourceConfig) call with loadSource():

geoComplyController.loadSource(player, sourceConfig);

Now at this stage you are all set. loadSource() checks the cached location token before every load and fetches a fresh one first if it's missing or expired, so the current token is attached to every roll request for this player automatically. If a roll still fails (missing, invalid, or expired token, or a detected proxy/VPN), the controller reports it through your error callback -- it does not retry the load itself; call loadSource() again (or let the user click Play again) to try with a fresh token. When you're done with a player, call geoComplyController.detachPlayer(player) (or stop() to detach all attached players).

Error codes

Every MKGeoComplyError.code your errorCallback receives is normalized to the form 4-100-<n>, regardless of which internal step produced it. <n> is either a raw GeoComply JWT SDK code (passed through as-is, message set to whatever errorMessage the SDK itself returned) or one of a small set of codes this plugin owns.

GeoComply JWT SDK codes -- the codes from GeoComply's own client SDK that can actually occur through this plugin's browser-based integration:

Code Meaning
4-100-600 There was an unexpected error.
4-100-602 There is no network connection.
4-100-603 The server communication failed.
4-100-604 GeoComply has suspended your account.
4-100-605 GeoComply has suspended your access to this SDK.
4-100-609 The custom fields list provided to the SDK is invalid.
4-100-610 Your app canceled the geolocation request.
4-100-611 The SDK canceled the request -- e.g. because required device location services are disabled. Reported before the request ever reaches GeoComply's Engine service.
4-100-614 Your app called verify() before the previous geolocation transaction finished.
4-100-620 Invalid server response.
4-100-635 User inputs (user ID, reason, phone number, or custom fields) contain special characters or symbols.
4-100-639 Your app did not set a reason code, but one is mandatory.
4-100-640 The HMAC value is invalid because the request was modified in transit.
4-100-647 The data expired from remaining too long in memory before submission.
4-100-670 Authentication JWT is invalid.
4-100-671 Authentication JWT is expired.
4-100-672 Public signing key not found in the GeoComply portal.
4-100-673 Failed to retrieve service configuration.
4-100-674 Client has not been authenticated (authenticate() not called or auth data is null).

Codes this plugin reports itself -- used for anything that isn't a direct GeoComply JWT SDK response:

Code Fires when
4-100-100 The KSS call to Azuki itself failed (network error, non-2xx response), or any other uncategorized failure.
4-100-101 Azuki rejected the roll's location token as missing, invalid, or expired.
4-100-102 GeoComply isn't configured for this backend (MKEnvironmentConfig.kssUrl not set).
4-100-103 The browser's location permission isn't granted.
4-100-105 Azuki rejected the roll's location JWT specifically due to a detected proxy/VPN.

Quick links:

Settings

Member Visibility

Theme

On This Page