Contents

Introduction

The OX Upsell packages provide the ability to show advertisements to end-users who are just using a free service like "Webmail", for example. It gives hosting companies the possibility to take advantage of offering and selling premium OX services via in-app upsell.

When free-mail users click on premium features like "OX Files", an upsell dialog can be shown where the missing feature can be advertised via text, screenshots, and/or videos. Based on your specific configuration, the end-user can request a free trial period and/or directly buy the feature within the upsell dialog. The customer never has to leave the application to upsell as it's a seamless in-app upsell.

It is also possible for hosting companies to easily integrate their own online shop into OX Upsell, since the internal mechanisms are loosely coupled via events.

TL;DR

Upsell is: End-user has a set of capabilities. UI offers more than what's just available in order to promote things. Actions, e.g. inline links, that require missing capabilities trigger the in-app upsell. This process leads to a trial period or a new subscription. Technical challenge for the UI developer is to check what the end-user has, what can be shown beyond that, and how to handle upsell.

Events

Whenever the user starts an app or clicks on an inline-action, a capability-check is performed. For example, all inline actions have native support for such checks:

Capabilities

There are lots of different capabilities. They are defined server-side and simplified they're just strings. Let's keep it simple and understand them as either services (e.g. mobility), specific functionality (e.g. multiple_mail_accounts) or applications (e.g. calendar). Some examples:

calendar

contacts

facebook

infostore

mailfilter

multiple_mail_accounts

...

webmail

// list all available capabilities
_(ox.serverConfig.capabilities).pluck('id').sort();

Free-mail users might just have webmail and contacts. If infostore is enabled for upsell, end-users will see the link to store mail attachments, for example. But since this capability is missing, the event "upsell:requires-upgrade" is triggered which starts the upsell process. Of course, this process should unlock the capability infostore for the end-user.

Example dialog

Whenever the event "upsell:requires-upgrade" is triggered, there should be some response for the end-user, usually an upsell dialog should open. This can be implemented as follows:

If upsell is not enabled and the end-user lacks specific capabilities, the app or the inline-action is not shown or visually disabled. If upsell is enabled by the upper configuration, inline-actions are shown but just trigger the upsell event "upsell:requires-upgrade" if clicked.

/*
* if you want to create your own controls, you can use the following helpers
*/
var upsell = require('io.ox/core/upsell');
// check capabilities (space-separated)
upsell.has('portal webmail');
// get missing capabilities (would return "calendar" in demo mode)
upsell.missing(['portal webmail', 'contacts', 'calendar']);
/* checks if upsell is enabled for a set of capabilities
* true if at least one set matches
*/
upsell.enabled(['portal webmail', 'webmail calendar']);
/* convenience function: "visible"
* checks if something should be visible depending on required capabilities
* true if any item matches requires capabilities
* true if any item does not match its requirements but is enabled for upsell
* this function is used for any inline link, for example, to decide whether or not showing it
*/
upsell.visible(['portal webmail', 'contacts', 'calendar']);
// likewise if neither capability set nor enabled for upsell, we get a false
upsell.visible(['foo']);
// in case something weird happens (usually bad configuration) debug() helps
upsell.debug();
// and this one
_(ox.serverConfig.capabilities).pluck('id').sort();

Server settings

In order to configure this server-side, just create a new file upsell.properties or append to existing appsuite.properties (mind the double-slash; this in not a typo!):