indoona SDK for PhP

The indoona SDK for PhP will allow you connect your users to indoona and make requests on behalf of them.

Installation

The indoona SDK for PhP uses PhP Composer. To install it and solve all dependencies, go to the SDK's root folder and run:

php composer.phar install

Setting up your app

First you have to create an App, if you didn’t do it yet, and configure it. At the end of this process, you will obtain OAuth2 credentials to initialize the SDK.

Getting started

In this section you will learn the basic steps to connect your application with the indoona Open Platform using the PhP SDK. For a comprehensive explanation of the SDK, have a look at the SDK reference.

Initializing

The SDK comes with the Indoona\DefaultConfig.php class where you must specify all your Application's data:


class DefaultConfig {

    /**
     * put here the OAuth2 client Id assigned to your App
     */
    const APP_CLIENT_ID = '45623fa91d7819ac120bd8a2z0VwZ';

    /**
     * put here the OAuth2 client secret assigned to your App
     */
    const APP_CLIENT_SECRET = 'zsYdqrffalpnVTAH1ayBwk36CpGDkcCTEA541jkcFKzAEaiFkRgQbkXOJDr3Q4Wu';

    /**
     * put here the OAuth2 redirectUri you specified on your App
     */
    const APP_REDIRECT_URI = 'http://yourappdomain/redirect.php';

    /**
     * put here the OAuth2 scopes you specified on your App
     */
    const APP_SCOPES = 'basic';

    /**
     * put here the signature methods supported by your App
     */
    const APP_SIGNATURE_METHODS = 'md5';

}

Obtaining an Application Token

Once your application is initialized, you can obtain an OAuth token (app token) to perform requests towards the indoona API on behalf of the app itself.
The Authorization Provider comes with a method that fits this purpose and that can be invoked at any time:



$appToken = $sdk->getAuthorizationProvider()->getAppAccessToken()

With the app-level token you can invoke through the SDK all API that prescind from a particular connected user, as well as any API involving a specific user, provided that the corresponding user_id is specified as parameter.

Connecting users

In order to let users connect to indoona from your website, as well as from your mobile site and apps, you can add a button like the one in the HTML example below:

<script>
    function openIndoonaConnectionForm(connectUrl) {
        // open the indoona connection URL in a new form with
        // a valid window size
        window.open(connectUrl);
    }
</script>

<?php

require __DIR__ . '/../../vendor/autoload.php';

use Indoona\OpenSDK;

// get an instance of the SDK
$sdk = new OpenSDK();

// build the connection Url
$userScopes = array("basic", "user_phone");
$connectUrl = $sdk->getAuthorizationProvider()->getConnectUrlWithScopes("my_connection_state", $userScopes);

?>

<body>
    <div id="indoona-connect-btn" class="btn-connect">
        <a onclick="openIndoonaConnectionForm('<?php echo $connectUrl ?>')">
            <img src="/images/indoona-button.png" />
        </a>
    </div>
</body>

indoona provides standard images for these buttons at our Resources page.

Notice the Indoona\OpenSDK.php class in the PhP code snippet above: this is the standard entry point for using the SDK in your PhP code.

Once users have inserted and validated their indoona credentials (telephone number and verification code) and set their connection scopes, they are sent to the redirect url specified at App Creation stage. In our example the redirect url is mapped onto the following PhP page, in charge of completing the user connection task:

<?php

// OAuth2 Redirect page

require __DIR__ . '/../../vendor/autoload.php';

use Indoona\OpenSDK;

// get the received OAuth2 authorization code
$authorizationCode = $_GET["code"];

// get an instance of the SDK
$sdk = new OpenSDK();

// request a user access token based on the received code
$userToken = $sdk->getAuthorizationProvider()->getUserAccessToken($authorizationCode);

// here you should store the user access token in your database
// for future use...

// if your application allows users to configure some preferences, you may
// want to redirect them to the management page you specified in the App
// Management dashboard
header("location: your_management_url");

Note:
The user token obtained in the example above can be used in two different ways to authenticate all further API calls:

  • directly include it as a parameter;
  • get the connected user's id by invoking $userToken->getUserId(), and specify it as a parameter in conjunction with the app token.

Semantically, these are equivalent options, yet there are useful tips that it's worth considering: see our Guidelines to gain more insight into this matter.
In any case, please keep in mind that both kind of tokens will expire or may be invalidated, so be prepared to properly handle refresh procedures.

If you want your application to appear in the indoona app directory, that will let indoona users connect directly from it, you must handle calls on the dedicated url you provided at App Creation stage. An otp (one time password) is delivered to your application as a parameter: you will use this otp to retrieve the actual connect url the user must be redirected to.

In our example, the url for connecting your App from the official directory is mapped onto the following PhP page:

<?php

// Connection from Directory page

require __DIR__ . '/../../vendor/autoload.php';

use Indoona\OpenSDK;

// The application should check here whether the
// currently logged user (if exists) is actually
// *not connected* to indoona, otherwise prompt
// users for confirming their identity or
// logging in with another one

// get the received one time password
$otp = $_GET["otp"];

// get an instance of the SDK
$sdk = new OpenSDK();

// start the connection process passing the received otp
$connectUrl = $sdk->getAuthorizationProvider()->getConnectUrlWithOtp("my_connection_state", $otp);
header("location: $connectUrl");

Managing the connection

In many cases, you will need to give users a way to manage their connection with your application. This may be about letting users tune their notification preferences or select contents you make available from your service, and so on.
To this purpose indoona Open Platform allows you to specify a management url in the developer dashboard, to be invoked from within the indoona mobile or web client.
Typically you will make the same management url available from your website as well, provided that you properly handle different window sizes.

When the management url is called from a mobile or web client, it comes with two parameters:

  • otp: a one-time password associated to the requesting user, generated as from the previous paragraph;
  • fromapp: a boolean value that tells you whether the page was requested by an indoona mobile client, e.g. to decide about showing a button for disconnection (show the button when fromapp = 'false','0' or not given)

You should always validate a one time password received on the management url, to ensure that the requesting user is a valid one, possibly checking it against an existing web session. Verification is carried out by invoking a dedicated API, that returns the users's unique identifier.
In this example, the management url is mapped to the following page:

<html>

	.
	.
	.

    <body>

        <?php

        require __DIR__ . '/../../vendor/autoload.php';

        use Indoona\OpenSDK;

        $otp = $_GET["otp"];
		$fromApp = $_GET["fromapp"];

		// you must always check that an otp is actually passed, as it won't be true if
		// the page is called from outside the app directory (e.g. from your website)
        if (!empty($otp)) {

			// get an instance of the SDK
	        $sdk = new OpenSDK();

			// retrieve the app-level access token
            $appToken = $sdk->getAuthorizationProvider()->getAppAccessToken();

			// obtain the id of the requesting indoona user
			$userId = $sdk->getApiProvider()->invokeOtpVerifyApi($appToken, $otp);

			// here you should check whether the obtained
			// user_id matches the one locally stored for
			// the currently logged user (if exists);
			// if yes, provide the management page’s content
			// (formatted according to fromApp's value),
			// otherwise you should raise an error

        }
        ?>

    </body>

</html>

Bring your entities into indoona

An important point of strenght of the indoona Open Platform is the possibility to bring any kind of entities from your domain into indoona, mapping them onto contacts that connected users will find in their indoona address book.

You may add contacts acting on behalf of your Application (e.g. a customer care contact available to all users), or let each connected user decide what to import on the management web page you declared at App Registration stage.

When you bring a new contact into indoona, you must provide display name and (optional) avatar url for that contact: these data will typically match corresponding ones in your domain, if existing, but you can decide otherwise.

In addition, for each contact you can specify a set of capabilities:

  • group_add: the contact can be invited into indoona groups;
  • interactive: the contact can process incoming messages (other than group notifications, that are always forwarded to your service).

Contacts can be removed or updated at any time.

.
.
use Indoona\OpenPlatform\Sdk\Model\Contact;
.
.

// retrieve user access token for the involved user (e.g. from persistency)
$userToken = ...;

$caps = array("group_add", 'interactive');

$contact = new Contact("numeric_id_in_my_domain",
	"Smart Lamp (Living Room)",
	"http://myappdomain/resource/smartlamp.png",
	$caps);

// get an instance of the SDK
$sdk = new OpenSDK();

// add the created contact
$sdk->getApiProvider()->invokeContactAddApiWithUserAccessToken($userToken, $contact);

N.B.: your Application is endowed by default with a supercontact, named after your application, that is allowed to send messages to any connected user.

Follow our Guidelines to learn about best practices in working with contacts.

Send your first message

After you added one or more contacts to a user’s indoona address book, you can start sending messages to that user on behalf of them. You can send text messages, as well as stickers, locations, pictures, movies, audio notes and generic files.

.
.
use Indoona\OpenPlatform\Sdk\Model\Message\Message;
.
.

// retrieve user access token for the involved user (e.g. from persistency)
$userToken = ...;

// get an instance of the SDK
$sdk = new OpenSDK();

// send a text message to the user
$msgStr = $sdk->getApiProvider()->invokeTextMessageSendApiWithUserAccessToken($userToken,
	"numeric_id_in_my_domain", $userToken->getUserId(),
	"Hi, I'm the smart lamp of your living room! I accept the following commands: 'on', 'off', 'more' and 'less' ");

// the API above returns a string representation of the message just sent:
// by means of the message factory, it can be inflated into a PhP object
$msg = $factory->buildMessage($msgStr);

Receive messages

Besides sending messages, your App can also receive messages from indoona. In order to enable message reception you must declare a valid endpoint URL, as specified in App Creation. A message is delivered to your endpoint over a POST request with JSON body: if you specified a signature method in the app's detail page, the packet carrying message data is signed using that method and according to the algorithms described in Message Reference. In our example, the endpoint URL is associated to the following PhP page:

<?php

require __DIR__ . '/../../vendor/autoload.php';

use Indoona\OpenSDK;
use Indoona\OpenPlatform\Sdk\Model\Message\MessageFactory;

// get an instance of the SDK
$sdk = new OpenSDK();

// Extract message data:
$msgData = $_POST['data'];

// Extract possible packet signature and signature method:
$msgSign = $_POST['signature'];
$signatureMethod = $_POST['signature_method'];

// Verify the message signature:
$isDataSafe = true;

if (!empty($msgSign) && !empty($signatureMethod)) {
	$isDataSafe = $sdk->getSignatureProvider($signatureMethod)->verifyPacketSignature($msgData, $msgSign));
}

if ($isDataSafe) {

	// Use the MessageFactory to build a Message instance with
	// the received JSON string:
    $msg = MessageFactory::getInstance()->buildMessage($msgData);

	// handle the received message according to your business logic
	.
	.
	.

}

Talk in groups!

Every contact featured with the 'group_add' capability can be added to indoona groups by every user who owns it. Notice that contacts can be owned by more than one connected user, to reflect scenarios in which the corresponding entity in your domain is shared among multiple users.

When a contact is invited to a group, on the endpoint URL you will get a JSON message structured as follows:


{
		"id"		:	"21kj3h12oh3o",
		"type"		:	"group-invite",
		"timestamp"	:	"1434613275796",
		"sender"	:	"aewd558asta9c4sot4fkfj34l@indoona",
		"room"		:	"dcsurakhg9x4a1rlqxjuawazq",
		"owner"		:	"aewd558asta9c4sot4fkfj34l@indoona",
		"recipient"	:	"333@appdomain",
		"data"		:	{
							"subject" : "My group",
							"avatar": "http://myavatar.com/my-group-avatar.jpg",
							"occupants": [
								{"id"	: "aewd558asta9c4sot4fkfj34l@indoona"},
								{"id"	: "333@appdomain"},
								{"id"	: "15@anotherappdomain"}
							],
							"policy": "open"
        				}
}

The "room" value is the unique group’s identifier, while the "owner" value is the identifier of the inviting user, among the ones who own the contact.

Let $inviteMsgStr be a string holding the JSON representation of a group invite message: like any other received message, it can be inflated to a serializable/deserializable object by means of the message factory:

.
.

use Indoona\OpenPlatform\Sdk\Model\Message\MessageFactory;

.
.

$msg = MessageFactory::getInstance()->buildMessage($inviteMsgStr);

// From the received message, your application will read and gather:
// - the room id
// - the group owner (i.e. the inviting user)
// to be specified respectively as recipient resource and authenticating user when the invited contact will send a message to the group.
$roomId = $msg->getRoom();
$owner = $msg->getOwner();

Similar messages are delivered to your service in correspondence of all events regarding that group (e.g. join/leave of other participants).

Now you are able to send your first message to the group on behalf of the contact just invited:

// retrieve user access token associated to $owner (e.g. from persistency):
$userToken = ...;

$msgStr = $sdk->getApiProvider()->invokeTextMessageSendApiWithUserAccessToken($userToken,
	"smart_lamp_id_in_my_domain", $roomId,
	"Hi everybody in the house from the smart lamp of the living room! I will notify you all when I get turned on or off, but only privileged people is allowed to tell me what to do!");

Follow our Guidelines to learn about best practices in working with messages.