You’ve watched the videos. You’ve ordered your free developer kit. You’ve played with the demos and registered your app.

Now you are ready to build a SnowShoe app of your own.

But what do you do first? This guide will take you, step by step, through building a Hello World web app on the Snowshoe platform. When we’re done, you will understand exactly how the Snowshoe system works, and how to integrate it into all of your amazing projects.

“Hello World”

Lets talk a little bit about what we want our app to do. To demonstrate the most basic functionality of the stamp, lets make an app that, when stamped, displays a hidden message specific to the stamp that was used.

In the finished product, if you stamp with the purple developer stamp, the app returns “hello world”. If you stamp with the orange stamp, you get “hello moon”.

Go to http://snow.sh/helloworld to see the finished product in action.

Step 1: Register your app and get snowshoe API credentials

First, we need to register our app with SnowShoe’s API. This will generate all of the credentials we will need to interact with the API endpoints.

The first thing you should do is log into the snowshoe developer portal. This is your one-stop-shop for creating, modifying and monitoring all of your snowshoe applications. Simply log in with the username and password you chose when you requested your developer kit.

Once logged in, you should see something that looks like this:

The applications view lists all of your snowshoe apps. If you followed our First App Wizard, the app you created should be listed here.

Click the blue “New App” button. This will bring up an “App Details” page:

All we need right now is a name. Enter the name of your choice in the top field, scroll to the bottom of the page, and click “save”.

Step 2: Getting Comfortable with the Stamp Screen

A new header should have just appeared that displays your new app’s Name, its App Key, App Secret, and three urls (Stamp Screen, Debug Callback, and Serial Number Identifier):

The first thing we are going to look at is the Stamp Screen. The stamp screen is a webpage that observes a stamp interaction and reports the observed touch coordinates back to your app.

While you are more than welcome to build and host your own stamp screen (and we have stamp screen SDKs available to get you started), we’ve spent a lot of time writing and rewriting a lot of javascript to get a stamp screen that works really well on all the phones and tablets we’ve tested. We host one of these highly optimized stamp screens for each app you build, and they are certainly the fastest way for you to get an app up and running.

Your app should redirect to its stamp screen url whenever you want your user to use a stamp. Go ahead and click on the “send to mobile” button next to your stamp screen url. We will send you an email with a link to you stamp screen. Open that link on your mobile device, and you should now see a stamp screen displaying our default green animated GIF.

Step 3: The Callback URL

Now, at this point, if you stamp your stamp screen with one of your developer stamps, you will just see a JSON output printed to the screen. Thats because we haven’t yet specified a callback URL. Your callback url is the endpoint on your server that receives data from the stamp screen.

You can still stamp your app’s stamp screen without specifying a callback url. Your stamp screen then simply POSTs its data to a default endpoint on our system that calls our API internally and then outputs the API response. That endpoint is your debug callback.

However, you want your stamp screen to post data to YOUR endpoint, or callback, and then you can call the API yourself and do things with the response.

Step 4: Building your callback.

Remember, we are building a callback that uses the Snowshoe-hosted stamp screen, so we need to have a server with a publicly-accessible URL.

The idea here is that we need a server endpoint that a stamp screen can send data to. The data that the stamp screen is going to POST to this callback is called “data”, so, for instance, in Python you could access it as request.POST[‘data’] . That data then needs to be POSTed to our API using OAuth 1.0a, signed using your app secret, and the response will be a JSON containing information about the stamp.

We maintain a Python SDK and a PHP SDK which are easy assets you can use to build the OAuth request. Obviously, you can build the OAuth request yourself, or there are a bunch of community-supported SDKs for languages other than Python and PHP.

The important part is that you take the data that is posted from the stamp screen to your callback, construct an Oauth 1.0a request around it, sign it with your app secret, and call our API using a POST request. The response from that request will be a JSON object containing information about the stamp event.

IMPORTANT! Once you’ve got your callback set up and accessible via a public URL, you need to enter that URL into your app, back in our developer portal. When you get to the app list after logging in, click on your app, scroll down to the Callback URL field, enter your URL, and click Save.

Step 5: Parsing the JSON response

Our API returns the following JSON once we’ve called the API successfully:

{“stamp”: {“serial”: “DEV-STAMP”}, “receipt”: “o8FLLwYW7TVjtO4VTUP4IgQvvvI=”, “secure”: false, “created”: “2013-05-24 23:01:23.274865+00:00"}

You can see that the first element is a “stamp” object, with a “serial” attribute. That serial is the stamp’s “name”. While all developer stamps have the same serial number, when you move to production stamps, each stamp will have their its own special serial number specific to your app.

Step 6: Making the Magic Happen

Sweet! We now know which stamp our user touched to the screen, and we simply need to write a callback that displays the correct message for each stamp.

Here is the code for your callback in Python:

from sssapi import Client
from django.views.decorators.csrf import csrf_exempt

from django.http import HttpResponse

@csrf_exempt
def callback(request): 

   client = Client(app_key="abcdef", app_secret="ghijkl") 

   response = client.call({“data”: request.POST[‘data’]})

   if response.has_key(‘stamp’): 

      if response[‘stamp’][‘serial’] == “DEV-STAMP”: 

          return HttpResponse("Hello World")

      if response['stamp']['serial'] == "DEV-STAMP-B":

           return HttpResponse("Hello Moon")

  else:
      return HttpResponse(“Invalid Stamp!”)

Here is the code in PHP:

include ("./inc/SSSApiClient.php");

$app_key = "abcdef";
$app_secret = "ghijkl";

$data = $_POST[‘data’];

$client = new SSSApiClient($app_key, $app_secret);
$JSONResponse = $client->processData($data);

$response = json_decode($JSONResponse, true);

if(array_key_exists(“stamp”, $response)){

  $serial = $response[‘stamp’][‘serial’];

}else{
   $serial = false;
}

if($serial==”DEV-STAMP”){

   echo “Hello World”;

}

if($serial == “DEV-STAMP-B”){

   echo “Hello Moon”;

}

if(!$serial){

    echo “Stamp not found!”;

}

The key is that your callback leverages the serial number of the stamp that was returned to make your app do something special. Here it’s just a “Hello World” message. But the possibilities are limitless.

That was fun, but what’s next?

There are a whole bunch of ways you can customize the SnowShoe stamp screen. Learn more here.

Have more questions? Check out the rest of our docs at beta.snowshoestamp.com/docs/.

Don’t have a SnowShoe developer kit? Order a free one TODAY!