Introduction

This tutorial will help you setup a barebones Flock app that users can install and it will save their authentications tokens.

The app you will end up with at the end of this tutorial isn't very useful by itself, however authentication tokens are crucial for calling methods, so understanding this is important.

Setup a public HTTP endpoint using ngrok

ngrok is only required if you can't setup a public HTTP endpoint for your app (e.g. on your development machine). 

  1. Download the client from the ngrok website
  2. You need HTTP forwarding for your app to work

    ngrok http 8080

    This will forward all requests on the ngrok forwarding URL to a HTTP service running on port 8080 locally.

  3. In the ngrok console that opens up, look for rows starting with Forwarding and copy the HTTPS URL from that row (i.e. one that looks like https://xxxxxx.ngrok.io).
  4. We will call this URL your app's base URL.

Setup your app in Developer Dashboard

  1. Visit the Developer Dashboard and click on Start creating a Flock App.
  2. On the Create Flock App screen, provide the following fields
    1. App Name – The name of the app
    2. App URL – A unique identifier that is used to form your app URL (i.e. https://apps.flock.co/<identifier>)
    3. Description – A longer description about your app
    4. If you'd like, you can choose custom icons and a unique background color for your app too
  3. Click Save.
  4. On the next screen, under the field Event Listener URL, provide the following URL: https://<base-url>/events. This will send all events, including the one we are interested in (app.install), to this URL.
  5. Scroll down and click on Save.
  6. You will be given the app Id and the app secret on the next screen. These will be required later.

Setup your app

You will need to

  1. Setup an HTTP listener on port 8080
  2. Listen for all requests sent to the path /events (i.e. the local URL). All events are sent to this URL, including app.install, which contains ids of the users who install your app and the corresponding authentication tokens to make method calls on their behalf.
  3. For each event that you receive, first verify the event token (provided in the X-Flock-Event-Token header of the HTTP request). The app secret is used to sign the event token; you can verify the event token by using the same.
  4. The request body contains the event information in JSON form. For app.install, the JSON looks as follows:

    {
        "name": "app.install",
        "userId": "u:cfc76545-3400-4864-892a-513a9f4ae409",
        "token": "4458f0a9-eca7-4efb-8560-2a0fd3ac858d"
    }

    This contains both the user identifier and the authentication token required to make method calls.
    (For good measure, you should also listen to app.uninstall and delete authentication tokens for users who uninstall your app).

  5. Save the identifier and the corresponding token – they should be persisted in permanent storage, as you will need this authentication token to make any method calls in the future.
  6. Make sure that your app returns a 200 OK response to the HTTP request containing app.install. If it does not, the app will not be installed.

Installation

Go back to the developer dashboard and open the app. Click the Install button at the top of the page, this will install the app into your own Flock account and send the app.install event to your HTTP listener.

Source Code

You can easily perform these steps using our SDKs. We've provided source code for a sample node.js app that does this using our node.js SDK.