Hello App

Let’s write a simple Hello App.

Throughout this article, we will go through the creation of a basic Hello App.

It will showcase:

  • A simple API to install/configure/uninstall the App
  • A simple usage of the javascript SDK

Your vendor record

We assume that you have a vendor record. You can check the dedicated section in the quickstart guides to create your own.

Declaring the App

To declare an App, you will need Administrator access:

  • Connect as Administrator
  • Go to Marketplace
  • Click on the '+' button

We will not be filling all the fields:

  • Name: choose a name
  • App code: choose a lower case reference with no spaces
  • App url : the URL of  your server that will handle incoming request. We can put a dummy value for now.

Once you saved, 2 unique identifiers will be generated that will be needed for the App's installation and subsequent API calls:

  • Reference: a readonly code starting with 'API' displayed above your App's Name field.
  • Key: a readonly code that contains 21 characters.

 

Code

You can find the code for the example App here.

The code is structured as so:

├── boondmanager.php
├── index.php
├── init.php
└── README.md

  • boondmanager.php: a set of helpers to handle the signedRequest and low level operations for API calls.
  • index.php: our App main file that will handle all requests.
  • init.php: declaration of the constants necessary to our App:
    • APP_KEY: the code that contains 21 characters.
    • APP_REFERENCE: the reference on the app card starting with 'APP'.
    • APP_CODE: optional. Used if you restrict access to your App via a code.

We also provide a javascript SDK that you can check here . It is hosted on Github temporarily but we will be making it available very soon on https://ui.boondmanager.com/sdk/boondmanager.js). It remains accessible and usable as an external script within the App's page. This section describes its functions in more detail.

Notes on index.php

  • $_REQUEST['script'] is the result of the rewriting rules where we store the end-point in a variable.
  • $_REQUEST['function'] is the result of the rewriting rules where we store the parameter function. For more details on how the function parameter see the section App's view rendering in the Quick-start Guides.
  • In this app the appToken si automatically stored in a file appToken.txt. We recommend that you store the token for production use in a more secure way. Be sure that your scripts have write access to their directory. The installation will succeed even if writing to appToken.txt fails.
  • How a call to /install is handled:
define('APP_CODE', your_APP_CODE_here);
// handles the first request with the installationCode
if($data && isset($data['installationCode']) && $data['installationCode'] == APP_CODE) { ... }
         
// handles the second request with the appToken
if($data && isset($data['appToken']) && isset($data['clientToken']) && isset($data['clientName'])) { ... }

When installing an App, 2 POST requests are sent to the App's install end-point. It has to handle the 2 cases. Only the first request contains an installationCode.

Web server requirements

The App will need to be hosted on one of your servers. To be able to use the example code, we will need:

  • PHP
  • TLS enabled on a server
  • An HTTP Server

A self-signed certificate is acceptable for testing but not for production. If you expose your self-signed certificate to the internet, visitors to your site will be greeted by security warnings.

For our testing purposes, you can use an Amazon AWS instance. We recommend these steps:

URL rewriting

We provide a .htacess file for Apache2 or httpd that showcases a set of rewriting rules. You can copy the rules in your .htaccess file and adapt them to your specific directory structure.

Once the server is ready, you can place the App's code in a directory served by the HTTP Server.

Testing your App's setup

Enter the constants declared in the file init.php with the values noted during the declaration of your App.

Test your App's base URL in a browser to check that it is accessible.

Completing your App's profile

Now that your App is accessible:

  • Go to Marketplace
  • Open your newly created App's profile
  • Click on Modify
  • Update the fields App url with your App's base URL

Installing the App

  • Go to Marketplace
  • Open your App's profile
  • Click on Install

Once the installation process is done, the App should be available among your Apps. You can see the installed Apps by accessing the My Apps page.

Activating the App

The App has to be activated for each manager:

  • Go to Managers/Roles
  • Access a manager's profile
  • Click See this role profile. It will display Apps and Security sections
  • Activate the App for the manager

Testing the App from Boondmanager

Now that your App is installed and activated for a specific manager, we can test it:

  • Log in using this manager's credentials
  • Open My Apps page. Your App should be available.
  • Open the App to display its page (cf see the default case in index.php
Cet article vous a-t-il été utile ?
Utilisateurs qui ont trouvé cela utile : 1 sur 7

Commentaires

0 commentaire

Cet article n'accepte pas de commentaires.