Capturing votes on Widgets as external users

Overview

A very powerful feature of Stackla is the ability for interactions such as votes and comments to be permitted only for specific users, and controlled by the embedding page. What makes this even better is that those users don’t need to be Stackla registered users at all. We call this feature Parent Page Permissions (P3).

At present, this feature is available only on the Slider, Quadrant, Nightfall and Waterfall widgets.

As per Stackla’s internal feature documentation:

Parent Page Permissions feature allows developers to specify a User ID when integrating a Widget onto the page. When a User ID is used, interactions such as voting or commenting will be recorded against that specific user. Note that the User ID can be any string up to 255 characters in length. This might be the ID of a user from your site, an IP address, a random session GUID – anything you like.

Key concepts

Parent Page Permissions

Parent Page Permissions allows a page embedding a Stackla widget to add personalisation to the data posted into Stackla in a secure manner. For example, this includes associating a vote on your site to be associated with a user within your context — not a Stackla user.

Example Application

The P3 concept may be a strange concept to some, hence this example will be kept to be very simple to illustrate how a page embedding a specific P3-enabled Widget may look, and what’s important about getting right.

To illustrate this, we will create a page that allows for voting to only be carried out by logged in users. To simulate this, we will use a faux user ID that would be available to a page if it had a login ability on it. Votes will only be allowed by users who have this ability, and clever users will not be able to generate requests in pretence that they are another user.

The Fun Part

Getting Started

In this example we will need to do the following, observing the output:

  1. Create a Widget with P3 and Secret Key configured
  2. Create a view with correct user info on it
  3. Create a view with incorrect user info on it

Create a Widget with P3 and Secret Key configured

Creating a Widget with P3 is similar to creating any other Widget, with the exception that we will enable the Parent Page Permissions option.

Just about every CMS has a similar concept of templated views in which you can use parameters of some kind to insert dynamic data from the DB. In this case we are using a Mustache-like template that will allow us to dynamically specify. Note the parameters/variables widget_id, widget_hash, user_id and user_hash.

p3page.html

Create a view with correct user info on it

Assume that the Widget ID we are using is 9999 and the hash is abcdEFGH1234. Both of these will be made available to you by the embed code when you generate the Widget.

Further, let’s assume that the user ID on the site is 1001. To generate the user hash, we can perform a SHA256 HMAC hash against the P3 secret (in this case “ThisIsMyKeyAndItCanBeAnything”) and user_hash. The following is an example of how to generate using PHP (via the hash_hmac function), but other languages have similar methods.

generate-hmac.php

In this case, the result is “d9c2cb2c9593e378ece57188c26f40e07b29d002f03691ec217b098e2245706c”, and the resulting generated HTML should look like the following file.

p3page-generated.html

Perform a vote with legitimate hash

When correctly configured, this Widget will now allow votes from the logged in user — in this case, user ID 1001.

When the user has voted on a tile successfully, the counter will increase and the feedback will be shown to user, with whatever treatment the Widget is configured with.

In the back-end, we can see the votes that correspond to this user via the “extusers” API, which can be found in your API console. when running against user 1001, we can see something like the following output for this user.

Create a view with incorrect user info on it

To demonstrate what would happen if the hash did not matcht the user ID, we can trial with the following code.

p3page-incorrect.html

As you can see in the following screen-shot, when trying to vote on a tile with the wrong hash, the backend will not allow it. Note that the front-end does not know what is a correct or incorrect hash since it does not know your secret word — only you and Stackla do.

Summary and Next Steps

This example can be further expanded with the following activities:

  • Dynamically encoding and generating the user hash from your CMS
  • Integrating a widget which can be voted on, with a widget that has voting disabled for users who aren’t logged in
  • Grabbing webhook notifications when somebody votes and correlating them with your user data

Want to stay up to date with all the latest Stackla developer news? Sign up!

Last Updated on 12 October 2014 5:27:12 GMT