“A rubber duck’s notification…” part II — The initial attempt

What do you call a duck that steals? A robber duck!

Hello there! This is the second chapter in the rubber duck fairy tale, a short series about implementing the Pushwoosh Web SDK and integrate it with the existing PushwooshPlugin from OutSystems.

So, in the previous article, besides the regular chit chat and gibberish, I’ve presented why are these articles coming out separately (non that important) along with our business case. In this article, I’ll present the first attempt that we took integrating Pushwoosh Web SDK with OutSystems. Because I want you to not miss anything and feel completely at home, the stupidest jokes about rubber ducks will continue — but I promise they will quack you up! Fine, I’ll stop.

Initial attempt: a non-reusable implementation.

Our goal is to have a reusable component fully integrated with the Pushwoosh plugin. But first things first: before making it reusable, we need to have it working. Sounds fair, right? Cool.

In order to make it work, I went to the Pushwoosh Web Push SDK 3.0 documentation page where we can find the SDK ZIP file along with a detailed walk through of the required steps. As you might have seen now (assuming you have downloaded the ZIP file and extracted it), the steps are really simple: edit the manifest.json file and put both on the top-level root of your website directory. Even the contents of the manifest file don’t seem daunting: you just have to edit three fields (name, short_name and gcm_sender_id) and we’re good to go!

Figure 1 — manifest.json file contents.

Wondering where do you get the gcm_sender_id? Well, the Google Cloud Messaging (GCM) service is now deprecated and has been replaced by the Firebase Cloud Message (FCM) service. Lucky for us, the guys from Pushwoosh have created a guide on how to migrate/obtain your FCM sender identifier.

Now that we have the SDK and the modified manifest file for our application, it’s time to import both files into OutSystems. How do we do it? Simple: go to the data tab, right-click on the Resources folder and then select “Import resources”. On the gif — and I say gif, not jif — below the pushwoosh-service-worker.js file has been imported already.

Figure 2— Importing resources into our OutSystems module

Now that we have added both files to our resources folder, we just need to make sure that those files are set to be deployed to our target directory, as seen on Figure 3. The target directory will be the root of the module, therefore the Target Directory parameter will be empty.

Figure 3— Our resource files need to be deployed to Target Directory.

If you’ve been following along and been paying attention, you might have noticed something: one of the “instructions” from the documentation specifically refers that those files need to be present on the top-level root directory. This means that by using the “Deploy to Target Directory” functionality it will be deployed, as the image above, to <root>/PWWebNotifications/ — which isn’t, obviously, the top-level root directory. So, how do we solve this?

If you are running on an Enterprise license, you can use the SEO functionality to point out an URL to your eSpace — as shown on Figure 4 and 5. But what if you don’t? Well, if you don’t, you’ll have to wait for part III of this series, in which we present a reusable implementation. But follow along.

Figure 4 — SEO Site Rules.

Figure 5 — Configuring a new Site Rule.

Independently if you’re running on an enterprise license or not, we still need to do three things: add the manifest.json file to our header, load the SDK asynchronously and initialize it.

In order to add the manifest.json file according to Pushwoosh documentation — they require it to be the first file of type (relationship) manifest — , we use the HTTPRequestHandler extension — included in the platform — to achieve this. The HTTPRequestHandler extension has the AddLinkTag action that, as the name suggests, adds a link tag to our HTML. Since we don’t have any more manifest files to add, we can use this straightforward way.

Now we have the second item of three: load the SDK asynchronously. Unfortunately, the HTTPRequestHandler is not suitable for this scenario, despite having an AddJavaScriptTag action. Why? Because it doesn’t allow us to specify the async flag. But what if it could…?

Everyone, meet HTTPRequestHandlerBuffed. This new extension is a “clone” from the HTTPRequestHandler but only contains one action: AddRawTagToHeader. This action uses the exact same behavior as the AddJavaScriptTag but instead of receiving a set of parameters and build a <script> element, it receives a text and just adds it to the header — as shown on Figure 6. This is a very powerful functionality and, as someone said before, with great power comes great responsibility. Be wise.

Figure 6— Adding a raw tag to the header.

Two out of three done, now it’s time to initialize our SDK. Again, according to the documentation from Pushwoosh, we just need to put this on our webpage:

Figure 7— Gist of our SDK initialization.

If you take a closer look at our gist, you’ll see some functions inside quotes. That is because we want to include this in our web page source, and we can do it using an unescaped expression — we use the EncodeJavaScript function to get rid of the warnings… and to get some security too.

If we look into the initialization options, there are a few ones that I would like to highlight:

• applicationCode: this is the application code that you see on the Pushwoosh Control Panel — as seen on Figure 8.

Figure 8— An entry on the application list visible on the Pushwoosh Control Panel.

• safariWebsitePushId: contrary to Chrome and Firefox, in order to receive push notifications on a Safari browser, you need to have a valid web push identifier — as seen on Figure 9.

Figure 9— Definition of a valid Safari push identifier on your Apple developer account.

• autoSubscribe: if the user shall be prompted to allow notifications as soon as the SDK is loaded and ready.
• userId : a unique user identifier — for the example above, we’re using the platform’s user identifier. This field is non-mandatory.

Ok, now that we have imported the files, loaded them on our web page and initialized the SDK, it’s time to test it. Let’s open the web page using the URL configured in the SEO properties and let’s hope it requests us to allow notifications on the website:

Figure 10 — Getting a notification prompt in Chrome.

And that’s it. We have a working version of our Pushwoosh Web SDK in the OutSystems platform. Let’s see if we can receive messages? Head over to your Pushwoosh control panel and send a notification to your browser only — this assumes you’re accepted to receive notifications:

Figure 11 — Pushwoosh control panel, sending a test notification.

This should fire a notification on our browser:

Figure 12 — Notification received on our test browser, Chrome!

That’s all for now folks! Part III of this series will bring us how we can convert this into a reusable component, all due to the help of rubber ducks. Living rubber ducks, for the matter.

Any complaints, questions or suggestions, feel free to drop a note here on send me an email to hello@armandogom.es!

Take care and see you in the next chapter!

Part III is out now. Check it here.

___________________________________________________________________

No footnotes this time. Woohoo!