indoona Open Platform Guidelines

The indoona Open Platform is an open and flexible framework that leaves maximum freedom to developers in shaping their services, giving them new ways to interact with their users and suggesting new and unexpected scenarios. Yet there is a set of common practices that would help developers providing their users with a consistent and smooth experience within the indoona Open Platform.

Application data

  • Take care of filling all mandatory and optional data of your application, putting extra attention on descriptions and icons. Descriptions must be as clear and exhaustive as possible. Icons must render well on indoona mobile apps;
  • Avoid any offending material in your application (i.e. name, icon, descriptions, stickers, etc..) as it will cause its rejection;
  • For your application to be more appealing in the application directory, choose a clear and impressive description and provide a good number of screenshots;
  • To make sure the users can find your application in our directory, choose carefully a meaningful set of search tags;
  • Specify a set of scopes, among the ones available, which strictly matches the need of your application towards the indoona platform: the less permissions you will ask to your users, the more they will be inclined to complete the connection process;
  • Use HTTPS on all URLs you declare for your application: OAuth2 redirect url, endpoint url and so on;
  • Specify a valid endpoint URL and listen on it for incoming messages: this will allow you to be notified when your contacts are invited in groups, and to let them properly interact;
  • Unless it does not apply at all for your application, provide a management URL to let your users tune their settings;
  • Specify a signature method for the messages that indoona will deliver to your service, in order to trust their actual source and their integrity;
  • If it applies to your application, create and upload your own sets of stickers to let your users enjoy a concise, effective and fun way of communicating with your service.

User connection

  • Use “Connect to indoona” or its translation as a caption for the button that starts the user connection process;
  • For the “Connect to indoona” button, use official images and specifications you can find at Resources page, according to the specific context where you host the button (web site, mobile site, mobile app);
  • If your users have an identity at your domain, you should place the “Connect to indoona” button within an authenticated section;
  • If your users don’t have an identity at your domain, you should implement some kind of persistence (e.g. reserve a token, create a user account…) to keep session and preferences of connected users;
  • If you want your users to experience a quick and smooth connection process from the application directory, you should implement the otp-based connection as described in the Getting Started section;
  • When you implement the otp-based connection, make sure to verify that the identity of the indoona user requesting the connection is compatible with the current one at your domain (see the Getting Started section for more details).
  • Use the most proper access token: as long as your application acts as a unique server-side component, it can - and should - rely on the app token; conversely, user tokens lend themselves to more flexible uses.
    Consider for example an application that, besides a server-side architecture, comes with its own mobile clients: user tokens may be distributed by the server-side component to the users' mobile clients, allowing them to autonomously perform API requests towards the indoona platform; this will typically yield benefits in terms of server offload.
    The same use case applies to an IoT application, where a given user token may be granted to all devices allowed to interact with the corresponding user.

Contacts

  • Adding contacts to users’ address books is a powerful instrument that the indoona Open Platform provides to your application to build a smooth and engaging experience: carefully plan how to map all kind of entities from your domain (e.g. smart objects, content feeds, support channels, etc..) onto indoona contacts. A contact doesn’t have to map just a single entity in your domain: you may decide to create contacts that map multiple entities, and vice versa;
  • After adding a new contact in a user’s address book, you should welcome the user on behalf of that contact with a proper message, possibly explaining how to interact with it;
  • If you featured a contact with the 'interactive' capability, you should provide a response to the 'help' text message which integrates possible explanations given in the welcome message

Messages

  • If a contact is added to one or more groups, consider if it should send its messages on all conversations or just in the last one. You may give the users a way to mute/unmute your contact on a given conversations.
  • The API for sending messages allows to specify whether a message will or will not generate a push notification in case the recipient is offline: you should not exceed in sending push notifications to your users, to avoid providing a possibly annoying experience. Two cases must be carefully handled:
    • not all events in a conversation are worth a push notification: for instance, in a football match your will send a push notification when the score changes and won’t send it in case of (minor) fouls;
    • if a contact is added to one or more groups, a user may not want it to generate push notifications on all conversations for the same messages: for example, it may stop sending notifications on the individual conversation.
  • Don’t overload user conversations with messages. A chatty contact may become annoying and affect the success of your application;
  • Send and receive the most appropriate kind of message for your application. For instance, if your application can give geolocalized weather information, tell your users they can send their location to your contact instead of typing the name of a place, and your application may answer with textual forecast as well as real-time weathermap pictures.