Using the full functionality built into our SnowShoe jQuery frontend library
It's entirely possible to use the SnowShoe jQuery library invisibly, making a screen stampable and delivering a payoff without anything visible to the user. However, based on our field tests and implementation stats, we highly recommend you use our progress bar animation to let users know when a stamp has been successfully recognized by the screen, as well as our help-messaging that will use dynamically generated on-screen notes to queue users into stamping best practices based on their inputs.
Progress Bar Animations
When using the SnowShoe jQuery module, you start by creating an object with initialization data at the bottom of the page or template you’d like to make stampable. This object houses variables that will determine how the stamp screen acts and how the stamp data is sent from your app to SnowShoe for authentication.
This module comes with the ability to trigger a loading animation as soon as a stamp is touched to the screen. View a video of this in action here. To use this feature,
1. Include snowshoe-sample.css. The loading animations are CSS-based and optimized for quick load times.
<!-- Snowshoe loader CSS -->
<link rel="stylesheet" href="snowshoe-sample.css">
2. Create a DIV with the ID of #snowshoe-progress-bar.
<!-- Snowshoe loader -->
<div id="snowshoe-progress-bar"></div>
3. Add the progressBarOn property to the initialization data object at the bottom of the page and set its value to true. The plugin will now handle the load animation by dynamically adding the class .snowshoe-progress-bar to the element that wears the ID #snowshoe-progress-bar.
<script>
var stampScreenInitData = {
"postUrl": "http://mydomain.com/stampscreen",
"stampScreenElmId": "stamp-screen",
"progressBarOn": true,
"postViaAjax": true, // post via Ajax
"success": function(response){
// handle success
console.log("Success!");
// clear animation
$('#snowshoe-progress-bar').removeClass("snowshoe-progress-bar");
},
"error": function(response){
// handle failure
console.log(" :-( ");
// clear animation
$('#snowshoe-progress-bar').removeClass("snowshoe-progress-bar");
}
}
</script>
<script src="jquery.snowshoe.js"></script>
The Snowshoe jQuery module dynamically adds the load animation class whenever five simultaneous touch events occur (i.e. a user touches a stamp to a screen).
4. Clear the animation.
To clear the animation when using AJAX
You'll notice above that we clear the animation in both the success and error callbacks. The animation will continue if you fail to do this, and your users may think the "stamp magic" is still trying to load.
To clear the animation when using HTTP POST
You'll likely be redirecting to another page upon a successful stamp interaction, so you will want to ensure that the progress bar animation is removed if a user returns to the stamp screen using the browser's back button. To ensure compatibility on the largest number of mobile browsers, we suggest adding the following code below your jquery.snowshoe.js reference.
<script>
window.onpopstate=function(){
$('#snowshoe-progress-bar').removeClass("snowshoe-progress-bar");
};
</script>
Feel free to override any of the CSS with your own. Also, if you’d like to implement your own loader, simply remove the progressBarOn property from your initialization data object or set it to false.
CSS Requirements
For the stamp screen HTML element, please ensure that its width and height properties are large enough to accommodate the full physical dimensions of your SnowShoe stamp. We suggest keeping the whole page stampable.
Help Messages
If a user is having trouble with their stamp, displaying help messages to them can be useful. With our latest stamp hardware, it helps to stamp and hold for a couple seconds on some devices. We've added dynamic messaging to this module allowing you to display custom messaging onscreen that will guide users toward best stamping practices. View a video of this in action here.
1. Include snowshoe-sample.css. This includes default styling to display the messages. Feel free (and you should) customize this css as needed.
<!-- Snowshoe messages CSS -->
<link rel="stylesheet" href="snowshoe-sample.css">
2. Create a DIV with the ID of #snowshoe-messages.
<!-- Snowshoe messages -->
<div id="snowshoe-messages"></div>
3. To add helpful messaging for when a user isn't touching the stamp to the screen fully, insert an HTML block in the initialization data in the format referenced below. First, a user will see a userTraining message for 2 seconds (instructs them to hold the stamp on the screen), followed by an insufficientPoints message (informs them to lift the stamp and try again). We used <h3> tags in the example but feel free to use any html you would like. It will be dynamically appended to the <div> with the id of #snowshoe-messages.
<script>
var stampScreenInitData = {
"postUrl": "http://mydomain.com/stampscreen",
"stampScreenElmId": "stamp-screen",
"progressBarOn": true,
"messages": {
"userTraining" : "<h3>Keep holding</h3>",
"insufficientPoints" : "<h3>Try again!</h3>"
}
}
</script>
<script src="jquery.snowshoe.js"></script>
4. If you are using AJAX to send stamp data to your backend, you can likewise append a helpful error messaging html block in the error callback to let your users know that a stamp wasn't recognized.
<script>
var stampScreenInitData = {
"postUrl": "http://mydomain.com/stampscreen",
"stampScreenElmId": "stamp-screen",
"progressBarOn": true,
"messages": {
"userTraining" : "<h3>Keep holding</h3>",
"insufficientPoints" : "<h3>Try again!</h3>"
},
"postViaAjax": true,
"success": function(response){
// handle success
console.log("Success!");
// clear screen
$('#snowshoe-progress-bar').removeClass("snowshoe-progress-bar");
$("#snowshoe-messages").empty();
},
"error": function(response){
// handle failure
console.log(" :-( ");
// clear screen
$('#snowshoe-progress-bar').removeClass("snowshoe-progress-bar");
$("#snowshoe-messages").empty();
// show failure message
$("#snowshoe-messages").append("<h3>That stamp was not found. Please try again!</h3>");
}
}
</script>
<script src="jquery.snowshoe.js"></script>
Again, feel free to override any of snowshoe-sample.css with your own. Just be sure to keep the element id #snowshoe-messages on the DIV to which you want to append your help message html blocks.