Integrating Pusher with Stamplay

In this post we’re going to take a look at the new Stamplay Web application framework. Specifically, we’re going to look at Pusher integration with Stamplay, allowing for advanced realtime features with very little programming required.

By the end of this tutorial you’ll have a working application that has a user login system powered by Google+ along with a photo upload system. Together, these systems will feed into a realtime activity feed showing logins and new photos as soon as they happen.

What is Stamplay

Stamplay is a Web application framework that aims to remove the hassle of back-end programming, allowing you to focus on the client side.

It works in a similar way to services like IFTTT and Zapier, using components and tasks to connect various external and data-related services in a simple way. You can then hook into the result of these tasks using a simple templating language within Stamplay itself. In short, Stamplay allows you to quickly put something together without the hassle of API integration or back-end tinkering.

For example, Stamplay has components that allow you to:

• Handle user accounts using services like Facebook and Google
• Store text-based data
• Use external APIs like Mailchimp, YouTube and Google Drive

Most recently, a Pusher component has been added allowing you to use realtime data within your applications in combination with any of the other components and services.

Using Pusher with Stamplay

Pusher is directly integrated into Stamplay, unlocking realtime functionality for your applications. It’s incredibly quick to get up and running!

We’re going to create a basic application on Stamplay that provides a realtime activity stream of user logins and photo uploads. Here’s a link to a working example so you can get see what the end result will be.

Create a Pusher account

The very first step is to create Pusher account in preparation for adding realtime features to your application. It takes about a minute so come back here when you’re done and we’ll continue.

Create a Stamplay account

Once you’ve set up a Pusher account it’s time to create a Stamplay account. Come back to the tutorial once you’ve finished setting everything up and we’ll start building the application.

Create application on Stamplay

Now that you have a Stamplay account it’s time to create the application that we’re going to use for the tutorial. There’s actually already an application already in your account when you create it but let’s create one from scratch.

Go to the Stamplay Editor and click on the “Create App” button. Enter a name for your application (I went for “Pusher Tutorial”) and click confirm.

If all went well, you’ll be taken to the components window of your shiny new application. This is where the fun starts!

Finding your application ID

Before we move on you need to grab your application ID as we’ll need it for setting up some of the components. It’s easy to get, just click on the Settings link in the left-hand menu, then General. Copy the AppId field and store that somewhere for reference later on.

Configure User component

You should see that the User component has already been added to your app. Click on it and you’ll be taken to the settings pages where we’ll customise the services to use for login.

For this tutorial we’ll be using Google as the login provider, though you can choose any of the other options. Just bear in mind that if you do, you’ll need to tweak some of the steps further on in the tutorial that relate to login.

When you select the Google service you’ll be asked for an App Id and App secret. To get these you need to go to your Google APIs Console and create a new project.

After creating a new project you need to set up your application credentials to share with Stamplay. The first step is to click on the Credentials link within the APIs & auth section on the left-hand menu.

We’re going to use OAuth so click on the Create new Client ID button and do the following:

• Select Web application
• Set Authorized JavaScript origins to https://APPID.stamplay.com (use the app ID you got earlier)
• Set Authorized redirect URI to https://APPID.stamplay.com/auth/v0/google/callback (change the app ID again)

If everything looks right then click on the Create Client ID button to save the authentication settings. Wait a few moments and you’ll be presented with all the authentication strings that you’ll need for Stamplay.

Copy the Client ID string and paste that into the App Id field back on Stamplay. Likewise, copy the Client secret string on Google and paste that into the App secret field on Stamplay.

Click on the Save button and we can move onto adding realtime.

Configure Pusher component

To add the Pusher component you’ll want to click on the big plus (+) icon at the top of the Stamplay Editor. This will take you back to the components page and from there you can click on the Pusher component at the bottom (with the red background).

At this point you’ll want to open a new tab and login to the Pusher Dashboard. We need to find your Pusher application settings so do that either click on the App Keys link within the default application called Main, or create a new application. You’ll see a page of code examples on the left and some connection settings on the right.

Copy the app_id given (ignore the quotes) and paste that into the Your App ID field on Stamplay. Repeat this for key and secret as well, ignoring the quotes.

When you’re done, click the Connect button and Stamplay will test that the connection to your Pusher app is working.

There’s one more component to set up and then we can start hooking it all together.

Configure User Photo component

Click the big plus button one more time to be taken back to the components screen. This time, select the User Photo component.

This component is very simple to set up. In our case, we’re going to set Admin Moderation to off and change per User to 0. This will make testing a lot easier but you’ll want to change these values when you’re ready to make your application public.

We’re done with the component setup, now it’s time to look at linking them together using tasks.

Create user login task

A task in Stamplay is the concept of a trigger and action. When something happens on a component (a trigger) it causes something to happen on another component (an action). It’s a simple but powerful concept that allows you to link together pretty much any service.

The first task we’re going to create is one to detect user login and send some information through Pusher when that happens. To do that you’ll want to click on the Tasks link on the left-hand menu and then on the New task button.

Select User as the trigger component and Login as the specific trigger to watch for.

Select Pusher as the action component and Send notification as the specific action to perform.

Click the Continue button, and click the Continue button again in the Tune User trigger section as we don’t need to add any filters.

You now need to define the Pusher message to be sent when a user logs in. This is where the magic happens, where the trigger data is used and passed to the action.

Set the Channel name to activity and the Event to login. The channel defines where to send the messages on your Pusher app, and the event defines what to call the message. You can read more about this on the Pusher documentation.

The Data field defines what to actually send through Pusher. Normally with Pusher this would be a JSON representation of data, usually a JavaScript object. However, in Stamplay you define different properties of the data to be sent as a line-separated list of pipe-separated (|) key|value pairs.

For example, the following JavaScript object:

javascript
1{
2  name: "Robin Hawkes"
3}
Copy

Would be written in the Stamplay Editor as:

javascript
1name|Robin Hawkes
Copy

In our case, we want to use a template value to represent the name of the logged in user. Fortunately, Stamplay provide lots of template values for you, the one we want to use being Display Name on the right-hand side. If you click on it you’ll see that it gets added to the Data field as {{user.displayName}}.

The final Data field should look like this:

javascript
1name|{{user.displayName}}
Copy

Click Create task and you’ll be taken back to the tasks screen.

Create photo upload task

The final task to define is the one that triggers a Pusher notification when a new photo is uploaded. Setting this up is pretty similar to the login task you set previously.

• Click on the New task button from the tasks screeen
• Select User Photo as the trigger component and New Photo Upload as the specific trigger to watch for
• Select Pusher as the action component and Send notification as the specific action to perform

Click the Continue button, and click the Continue button again in the Tune User trigger section as we don’t need to add any filters.

Define the Pusher message to be sent when a new photo is uploaded. The format is exactly the same as the message we defined in the Login task previously.

We want to send a Pusher message that would look like the following as a JavaScript object:

javascript
1{
2  url: "http://path.to/image-name.jpg",
3  author_name: "Robin Hawkes"
4}
Copy

The easiest way to do this in Stamplay is to use the template values again, in this case the Url and Display Name values.

When you’re done the Data field should look like this:

javascript
1url|{{photo.url}}
2author_name|{{user.displayName}}
Copy

Click Create task and you’ll be taken back to the tasks screen where you should see both of the tasks that we’ll be using.

At this point we’re done with Stamplay component setup and can move onto the HTML and actually making things display in your browser.

Add login and logout buttons to

All the HTML and front-end code is managed within the layout screen in Stamplay. To get there click on the Layout link in the left-hand menu.

Before we edit anything, let’s take a look at how the application currently looks. Find the Go to App link at the top right of the Stamplay Editor and open it in a new tab. You should see something like this:

The first thing we want to do is replace the 3 navigation links at the top with login and logout buttons. Fortunately, the code for this has been taken care of via a set of widgets that Stamplay provide.

Go back to the Stamplay Layout screen and open the layout.html page. This is the base HTML for your app, though right now we’re only interested in the navigation.

Replace the <ul class="nav nav-pills pull-right"> element (lines 24–28) with the following:

markup
1<div class="pull-right">
2  <div data-stamplay-widget="auth.login" data-channel="google" data-redirect="/"></div>
3  <div data-stamplay-widget="auth.logout"></div>
4</div>
Copy

These are Stamplay’s login and logout widgets. The important thing to notice with the login widget is the reference to to Google in the data-channel attribute. This is what you’ll need to tweak if you used a different service for login.

Click the save button (the little floppy disk icon) and refresh or re-open the application. You’ll now see a login button, which if you click will take you to Google for login.

If you log in in with your own account you’ll be taken back to your application and there’ll now be a logout button at the top of your application. That’s how simple it is to add user accounts to an application with Stamplay!

Add Pusher to

The next step is to add the Pusher JavaScript library to your application. Open up layout.html again and add the following to the bottom of the markup, above the <!-- GOOGLE ANALYTICS --> section (line 46):

markup
1<script src="//js.pusher.com/2.2/pusher.min.js"></script>
2<script>
3  // Enable pusher logging - don't include this in production
4  Pusher.log = function(message) {
5    if (window.console && window.console.log) {
6      window.console.log(message);
7    }
8  };
9
10  var pusher = new Pusher('YOUR_PUSHER_APP_KEY');
11</script>
Copy

Replace the YOUR_PUSHER_APP_KEY text with the key value you got from your Pusher Dashboard earlier on.

Save the changes and refresh the application with the browser console open (cmd + alt + j in Chrome).

If everything went well then you’ll see some logs from Pusher showing that a connection was attempted and successfully made.

Add UI to

Open up index.html in the Layout screen and remove absolutely everything from it, replacing with the following:

markup
1<div class="row marketing">
2  <div class="col-md-6">
3    <h4>Upload photo</h4>
4    <p>Upload a photo and watch it appear in realtime on the activity stream.</p>
5    <div data-stamplay-widget="photo.upload" data-album-id="stamplay-demo"></div>
6  </div>
7  <div class="col-md-6">
8    <h4>Activity stream</h4>
9    <div class="list-group activity-stream"></div>
10  </div>
11</div>
Copy

This sets up the UI elements needed to upload a photo and to act as a container for the realtime activity feed.

Click save and refresh the app to check everything looks ok.

The Add files… button is automatically generated using a Stamplay widget for the User Photo component. The widget is an simple as a <div> element with a data-stamplay-widget attribute set to photo.upload and a data-album-id attribute set to a name you want to use to group uploaded photos.

This widget will automatically hook into the component you’ve set up and will automatically trigger the tasks you’ve set up. It’s pretty cool!

Add Pusher listeners to

The final stretch is to connect the realtime activity feed HTML with Pusher. The first part of that is to set up the right event listeners for Pusher.

Add the following to layout.html underneath setting the pusher variable (line 56):

javascript
1var activityStream = document.querySelector(".activity-stream");
2var channel = pusher.subscribe('activity');
3
4channel.bind('login', function(data) {
5  userActivity(data);
6});
7
8channel.bind('new-photo', function(data) {
9  photoActivity(data);
10});
Copy

This will store a reference to the .activity-stream DOM element, as well as create a Pusher subscription to the activity channel that you defined in your Stamplay tasks.

The 2 bind calls set up event listeners for the login and new-photo messages that are being sent by the Stamplay tasks.

Right now these event listeners try and call non-existant functions to output something to the activity feed. Let’s fix that.

Add UI generation to listeners in

To generate the output for the activity feed we’ll use some basic DOM creation and manipulation in JavaScript. Feel free to use another approach if you wish. We’ll also be separating the logic into a function for each activity (login and photo upload), though you should probably merge this into a single function to avoid code duplication.

Add the following code to layout.html below the Pusher event binds that we set up earlier (around line 67):

javascript
1var userActivity = function(user) {
2  var item = document.createElement("div");
3  item.classList.add("list-group-item");
4
5  var html = '<h4>' + user.name + ' logged in</h4>';
6
7  item.innerHTML = html;
8
9  activityStream.insertBefore(item, activityStream.firstChild);
10};
11
12var photoActivity = function(photo) {
13  var item = document.createElement("div");
14  item.classList.add("list-group-item");
15
16  var html = '<div class="media">';
17  html += '<a class="pull-right" href="' + photo.url + '" target="_blank"><img class="media-object" width="80" src="' + photo.url + '"></a>';
18  html += '<div class="media-body">';
19  html += '<h4 class="media-heading">New photo</h4>';
20  html += '<p>Uploaded by ' + photo.author_name + '</p>';
21  html += '</div>';
22  html += '</div>';
23
24  item.innerHTML = html;
25
26  activityStream.insertBefore(item, activityStream.firstChild);
27};
Copy

These handlers take the data from the login and new-photo Pusher events and output them to the activity feed DOM element. JSON data from the events is automatically parsed by the Pusher library, allowing you to access it as a JavaScript object.

At this point everything is hooked up and ready to go. Let’s test it out!

Checking everything works

We’re going to test the app in 2 ways; the first via the Pusher Debug Console to test the events and the handlers, and the second using the app itself to make sure the Stamplay components and tasks are working correctly.

Pusher Debug Console

Instead of having to continuously log in and out of the app you can use the Pusher Debug Console to send fake messages that act exactly the same as the login and new-photo events that you’d be sending using Stamplay.

Log into your Pusher Dashboard and select your application. Click on the Debug Console link on the right and you’ll see a blank console. Open your Stamplay application in a new tab (or refresh it if it’s already open) and you should see some connection logs appear in the Pusher Debug Console.

While the visual logging of Pusher messages is useful, it’s the Create new Event form on the right-hand side that we’re interested in right now. This form allows you to send messages through your app using any channel, event and data that you want. It’s the pefect way to easily test things.

We’re just going to test the new-photo event for now but it would be a good idea to use the same approach to test the login event too.

Enter activity for Channel, new-photo for Event and the following JSON for Data:

javascript
1{
2  "author_name": "Some Person",
3  "url": "http://cl.ly/image/3Y2r0t3p2I1v/pusher-stamplay.jpg"
4}
Copy

Click Send event and hop back over to the tab with your Stamplay application open. If all went well then you’ll see a an activity showing that a new photo was uploaded.

If you don’t see this then you’ll want to check the following:

• That the message was confirmed as being sent to the right channel and with the right event name in the Pusher Debug Console
• That the message was received by the Stamplay application by using the JavaScript console in your browser

If the message is received in the JavaScript console then it’s likely that there’s a mistake in the name of the channel or event that you’re using in in the Stamplay tasks. Double check these to see if everything matches up.

Testing the Stamplay components

Once you’re sure that the Pusher integration works you can test the app properly. Refresh the application to remove the test activity and, if not logged in already, click on the Login button.

When you’re logged in, click on the _Add files…” button and select an image to use as a test upload.

You’ll see an Upload successful message and, if the Pusher component and tasks worked, a New photo activity on the right-hand side. If you see this then you’re all done, your Stamplay application with Pusher integration is fully functional!

If this didn’t work, check the Pusher Debug Console for events and the JavaScript console in the browser to make sure Pusher events were received. As above, any issues are likely due to mismatched channel or event names.

Sign up and get started

This tutorial should act as a good foundation for producing much more complex applications using Stamplay and Pusher. If you haven’t already, sign up to Pusher and get started today.

Have you made something with Stamplay and Pusher? Perhaps using their new Webhooks component. Let us know, we’d love to see it.