Blog Forum

Go back to other paywall features

Some businesses want to control their streaming process on per-user and per-stream level in addition to general protection methods like hot-link protection or geo restriction limitation. This is required especially for pay-per-view (PPV) systems where viewers pay for accessing the media.

What can we do?

WMSPanel and Nimble Streamer provide a framework which allows collecting detailed data for all connection and making decision to allow or deny each connecting user. This may be used for pay-per-view and pay-per-minute logic, calculating each user simultaneous connections, stats for unique visitors and much more.

These are the steps for a customer to integrate those capabilities into customer's workflow:

1. Implement PPV API handler which is able to accept POST requests.
2. Set up handler parameters within WMSPanel.
3. Add PPV signature into existing media links.
4. Enable PPV signature process via WMSPanel.

Having all that the general workflow would be as follows:

• Nimble Streamer sends request to handler on a periodical basis. The sync contains all users' IDs, IPs, delta of view time between sync-ups and media names.
• Customer handler makes required decisions based on company business logic and sends response to Nimble. This response specifies which users must be blocked from watching media.
• Blocked users are shut down immediately, while others keep watching.

So let's go step by step to implement it.

1. Create PPV handler

WMSPanel uses push API. Nimble sends requests to customer's handler. This handler must be accessible via HTTP/HTTPS and it must be able to accept POST requests. Those requests may be formed via either JSON or XML, this can be set up in WMSPanel settings.
Handler needs to do a few things:

• parse incoming request (e.g. decode JSON document);
• make query to internal users database to append consumption updates and make decision about who may keep accessing the media (e.g. watch video);
• return encoded response which contains users' IDs that must be blocked from accessing the media.

Handler needs to return list of all blocked IDs on every sync. If some ID is excluded from the list, it will be allowed to access.

Please check a basic handler example for PHP. It just takes incoming request, logs it and returns a couple of IDs to be blocked. You should take a look at full JSON request example and a handler response sample as well.

2. Set up API parameters for handler

Now we need to set up a link between Nimble Streamer instances and the handler. Select Control / API setup menu and select Push API tab which is the one we are going to use now.

Define the following:

• Enter handler URL into PPV handler URL field;
• Click on Enable pay per view check box;
• Select Request format or leave default "JSON" value;
• Enter Sync interval or leave default 30 seconds.

A few seconds after you click on Save, the first sync-up will be sent to your handler.

3. Make PPV signature

In order for Nimble to start sending requests, some changes must be made on your web server side. Media URL needs to be modified to include special signature, that would contain required information.

For example, you have this URL for your live stream:
http://video.wmspanel.com:8081/vod/sample.mp4/playlist.m3u8
The modified URL would be:
http://video.wmspanel.com:8081/vod/sample.mp4/playlist.m3u8?wmsAuthSign=c2VydmVyX3RpbWU9MDMvMDEvMjAxOSAwNzozMTo0NCBBTSZoYXNoX3ZhbHVlPVZGOHBLUE44Z0ZTYUQrM0p5c0pNYlE9PSZ2YWxpZG1pbnV0ZXM9MTAmaWQ9SURfMQ==

To generate signature you need to modify your front-end source to include code snippet.

Click here to see the sample code.

You can find all samples in WMSPanel github repository and adapt them for your use case.

Two important things must be specified here:

• user ID defined by the customer;
• key, or password, which is going to be used on the next step.

The ID is any string value which is unique within customer's scope. The code is the same as the code used in hot-linking protection except for the IP which is replaced with ID here.

Q: How do I use both client ID and IP in my signature?

If you add "checkip=true" option and IP address to $urlsignature, Nimble Streamer will check both client IP and user ID.
The signature generation code from example above will need to be modified like this:
$str2hash = $ip. $id . $key . $today . $validminutes;
$md5raw = md5($str2hash, true);
$base64hash = base64_encode($md5raw);
$urlsignature = 'server_time=' . $today . '&hash_value=' . $base64hash . '&validminutes=' . $validminutes . '&id=' . $id .'&checkip=true';

4. Set up PPV signature settings

To define restriction settings on server side, Nimble Streamer must be notified about it. The set up is made via WMSAuth paywall setup.
Click Control top menu, then choose WMSAuth paywall setup menu item.

WMSAuth group

In WMSAuth, every restriction may be applied to a group of servers. So the first thing to do is to create a group and assign one or more Nimble servers to it. Check this screenshot for details.

WMSAuth rule

Within a group, there may be several rules, each working with its set of streams. Just click on "Add rule" to enter rule creation page. See how you can specify Nimble streams regular expression on the screenshot below.

Set up password

Now you need to specify a key, or password, which was inserted into the media signature on web server side in section "Make PPV signature" above.
After you save the rule, it will be applied to the server within a few seconds.

Further usage

What's next

Now when the chain is set up you will be receiving updates on current streaming status. As response you can send back the blocked IDs list and so control your streaming workflow.

This functionality also works fine with geo-location and IP ranges restriction.

Also check out playback authorization feature set which allows controlling playback connections with external handler.

The Paranoid’s Guide to Internet Video Streaming by Thomas Gires is very useful to see real-life example of using pay-per-view feature set for HLS re-streaming via light-weight edge.

Q: Are there any debugging techniques available?

The debugging handler and interface allows receiving data from servers and viewing results via your browser. Use it to see what requests will come from your server instances to your own handler.

Q: How can I use mutual authorization with PPV?

Mutual authorization is the way your handler and your media server can make sure they interact with legit and authorized counterpart.

First you need to enable mutual authorization. Check the screenshot in Section 2 for "Enable mutual authorization" checkbox.

Once it's enabled, the designated media server will start sending additional parameters: "Signature" and "Puzzle" in addition to existing "ID".
"Signature" is what your handler need to check to make sure that is was your server who sent it.
Signature = BASE64(MD5(ID + Puzzle + Token))

Your handler response must contain "Solution" parameter, e.g.
{"Solution": "PjxTZXJ2ZXJBdXRob3JpemF0aW9uUHJvcGVydGllcz48U2Vydm"}
"Solution" parameter is checked by Nimble Streamer to make sure your handler knows the token.
Solution = BASE64(MD5(Puzzle + Token))

The "Token" parameter is set up in WMSPanel as shown on the same PPV setup screenshot.

Q: What if WMSPanel is not accessible?

Nimble Streamer will send requests and receive responses for pay-per-view framework regardless of WMSPanel availability. If your server can't connect to WMSPanel for some reason, this functionality will still work perfectly. Once the handler settings are set up, the control panel is not used anymore.

Any other questions or problems?

Check the paywall FAQ and search through our documentation to find more information.

See also:Live streamingAds insertionTranscoderCodecsVideo-on-demandBuilding infrastructureMobile solutionsUsage snapshotsQosifire