AppSuite:Upsell: Difference between revisions

From Open-Xchange
No edit summary
 
(147 intermediate revisions by 8 users not shown)
Line 1: Line 1:
=Upsell=
<!-- !!! -->
<!-- PLEASE APPLY CHANGES ONLY TO THE NEW TECHNICAL DOCUMENTATION: wd/frontend/web/documentation -->
<!-- !!! -->


__TOC__


The OX Upsell packages provide the ability to show advertisements to end-users who are just using a free service like "Webmail". It gives hosting companies the possibility to take advantage of offering and selling premium OX services via in-app upsell.
The content on this page has moved to http://oxpedia.org/wiki/index.php?title=AppSuite:OX_Upsell
 
Assuming a free-mail user clicks on a premium feature 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 user can request a free trial period and/or directly buy the feature within the upsell dialog with one simple click. 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.
 
==Events==
 
Whenever the user starts an app or clicks on an inline-action, a capability-check is performed internally. For example, all inline actions have native support for such checks:
 
<pre class="language-javascript">
new Action('io.ox/calendar/detail/actions/sendmail', {
    capabilities: 'webmail',
    action: function (baton) {
        // send mail
    }
});
</pre>
 
Assuming the end-user does not have "webmail" (for example in a files-only setup), a proper event is fired:
 
<pre class="language-javascript">
// if any action misses a capability
ox.trigger('upsell:requires-upgrade');
// which provides the following data for apps:
{
  type: "app",
  id: "io.ox/mail/main",
  missing: "webmail"
}
// and for inline-actions:
{
  type: "inline-action",
  id: "io.ox/calendar/detail/actions/sendmail",
  missing: "webmail"
}
</pre>
 
==Example dialog==
The event ''"upsell:requires-upgrade"'' should open an upsell dialog:
 
<pre class="language-javascript">
function showUpgradeDialog(e, options) {
    require(['io.ox/core/tk/dialogs'], function (dialogs) {
        new dialogs.ModalDialog({ easyOut: true })
            .build(function () {
                this.getHeader().append(
                    $('<h4>').text('Upgrade required')
                );
                this.getContentNode().append(
                    $.txt('This feature is not available.'),
                    $.txt('You need to upgrade your account now.'),
                    $.txt(' '),
                    $.txt('The first 90 days are free.')
                );
                this.addPrimaryButton('upgrade', 'Get free upgrade');
                this.addButton('cancel', 'Cancel');
            })
            .setUnderlayStyle({
                opacity: 0.70,
                backgroundColor: '#08C'
            })
            .on('upgrade', function () {
                ox.trigger('upsell:upgrade', options);
            })
            .on('show', function () {
                ox.off('upsell:requires-upgrade', showUpgradeDialog);
            })
            .on('close', function () {
                ox.on('upsell:requires-upgrade', showUpgradeDialog);
            })
            .show();
    });
}
 
function upgrade(e, options) {
    console.debug('upgrade', options);
    alert('User decided to upgrade! (global event: upsell:upgrade)');
}
 
ox.on('upsell:requires-upgrade', showUpgradeDialog);
 
/*
* convention: 'upsell:upgrade' is used to trigger final upsell
* the current user and user_id can be found in global variables ox.user and ox.user_id
*/
ox.on('upsell:upgrade', upgrade);
 
</pre>
 
Hint: For simple demo purposes, you can enable an internal upsell configuration by appending '''"&demo=upsell"''' to the URL. Needs to reload page, of course.
 
The second event '''"upsell:upgrade"''' can be understood as the final imperative to request the upsell server-side.
 
==Accessing upsell settings==
The upsell configuration is located in namespace ''"io.ox/core"'', path is ''"upsell/enabled"''. Example:
 
<pre class="language-javascript">
// get all capabilities that can trigger upsell
require('settings!io.ox/core').get('upsell/enabled');
 
// contains data like this
{
  infostore: true,
  portal: true,
  tasks: true
}
</pre>
 
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.
 
<pre class="language-javascript">
/*
* 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();
 
</pre>
 
==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!):
 
<pre class="language-settings">
io.ox/core//upsell/enabled/infostore=true
io.ox/core//upsell/enabled/portal=true
io.ox/core//upsell/enabled/tasks=true
</pre>
 
[[Category:AppSuite]]
[[Category:UI]]

Latest revision as of 10:39, 6 November 2019


The content on this page has moved to http://oxpedia.org/wiki/index.php?title=AppSuite:OX_Upsell