OX6:OX6-Upsell

From Open-Xchange

Upsell Gui

Introduction

The Open-xchange Upsell packages provide the ability to show the OX user advertisements for different OX features which are only available when he upgrades his account to a higher level of access rights like "Groupware" or "Mobility". It also enables hosting companies to easily integrate their online shopping system into Open-Xchange to directly sell features without actually leaving the Open-Xchange application / Gui. The upsell layer window will be shown if the user clicks on a deactivated feature like calender/infostore etc.

Upsell

We have implemented 3 different types of upsell possibilities:

  • Show the Upsell Layer window and trigger the upgrade via a generated email
  • Show the Upsell Layer window and open a configurable URL including all needed parameters after the user clicked "buy" or "trial.
  • Directly display a configurable URL/Online SHOP (systemwide or/and per context configurable) within the upsell Layer window instead of standard OX upsell content

The upsell layer has full i18n (EN and DE are included) support integrated and offers following components for advertisement:

  • Text
  • Video
  • Screenshots

to promote a certain feature for Open-Xchange.

The important part of the upsell layer is the ability to pass all needed parameters from users session like username,id,cid etc. + the feature he wants to buy, to a third party online shop system or send these parameters via email in machine readable (configurable) format to a dedicated mailsystem which can process it via procmail or similar to trigger the upgrade process via the Open-Xchange API´s (SOAP,RMI,CLT).

Installation

  • Download and install following OX upsell packages from the corresponding repository:
open-xchange-upsell-multiple
open-xchange-upsell-multiple-gui

After installation of these packages, you have installed one server side plugin and one gui-plugin. If you have dedicated apaches running in your setup, only install the "open-xchange-upsell-multiple-gui" package on them. The upsell layer is now available to ALL contexts/users of this OX application server/gui instance. All UI plugin contents are installed under following directory (on Debian based installations): 

/var/www/ox6/plugins/com.openexchange.upsell.multiple.gui/

It contains different subdirectories, for example: 

css  - All colors, styles are defined within this directory.

lang - All translated PO files must be stored below this directory.

templates - If you want to change/replace screenshots, videos, layouts etc. check this directory.

The server side plugin comes with some templates, for example to change the advertisement text which is sent to the user, or the mail which is sent to the upgrade processing email system. All of them are stored below /opt/open-xchange/etc/groupware 

upsell_mail_body_ox_enduser.tmpl
upsell_mail_body_ox_enduser.tmpl_de_DE
upsell_mail_subject_ox_enduser.tmpl
upsell_mail_subject_ox_enduser.tmpl_de_DE

Configuration

Once installed, all nessecary configuration can be done in one single file. This file can be found at the following directory on the OX application server: 

/opt/open-xchange/etc/groupware/upsell.properties

Switching between the 3 different types of the upsell layer, edit parameter: 

com.openexchange.upsell.multiple.method=

Possible values: "direct", "static" or "email".

direct = Redirect within IFRAME immediately to parameter "com.openexchange.upsell.multiple.method.static.shop_redir_url" or to the context specific URL value after clicking one of the upsell triggers.

static = Redirect AFTER clicking a button within the shipped OX Upsell pages to parameter "com.openexchange.upsell.multiple.method.static.shop_redir_url" or to the context specific URL value after clicking one of the upsell triggers.

email = Send email to specific address AFTER clicking a button within the shipped OX Upsell pages


Defining the redirect URL for method "static" and "direct" for all contexts which are not specially provisioned, edit parameter: 

com.openexchange.upsell.multiple.method.static.shop_redir_url=

Example: 

http://shop.host.tld/store?src=ox&user=_USER_&userid=_USERID_&mail=_MAIL_&login=_LOGIN_&imaplogin=_IMAPLOGIN_&clicked_feat=_CLICKED_FEATURE_&lang=_LANG_&cid=_CID_

As you can see from the example, the server side upsell plugin will replace all placeholders (_USER_ , _USERID_ etc.) with the data from the users OX session while he is logged into OX. You can use following parameters in this URL: 

"_USER_"
"_USERID_"
"_MAIL_"
"_LOGIN_"
"_IMAPLOGIN"
"_CLICKED_FEATURE_"
"_UPSELL_PLAN_" - Not in use.
"_CID_"
"_LANG_"
"_PURCHASE_TYPE_" - Only used if email or static method is used due to the OX upsell layout/buttons
"_INVITE_" - User checked "invite my friends" checkbox in upsell box

If you need a different URL than specified in this configurtion for one or mor e OX Contexts, you must set the custom attribute: 

"com.openexchange.upsell/url"

into the admin user of the context via SOAP,RMI OR Commandline Tools.

WARNING: Due to Database restriction, you can only set the URL without any PAR AMETERS. PLEASE ONLY SET THE HOST+PATH to your WEBAPP.

Following PARAMETERS will be automatically appended to the URL: 

src=ox&user=_USER_&invite=_INVITE_&mail=_MAIL_&purchase_type=_PURCHASE_TYPE_&login=_LOGIN_&imaplogin=_IMAPLOGIN_&clicked_feat=_CLICKED_FEATURE_&upsell_plan=_U
PSELL_PLAN_&cid=_CID_&lang=_LANG_


To set the custom attribute via Commandline Tools, use following example: 

changeuser -i 2 -c 424242667 --com.openexchange.upsell/url="http://my.reseller1.com/path/to/webapp/or/php_page.php?"


Defining the email address where upsell plugin will send all infos to for processing this request in a machine readable format: 

com.openexchange.upsell.multiple.method.email.address=

The mail will be send to this email address. It should be processed by some script via procmail or similar to trigger an API call later on.


Email template to load for sending the machine readable mail, if not found, hardcoded text will be used: 

com.openexchange.upsell.multiple.method.email.template=/opt/open-xchange/etc/groupware/upsell_mail_body.tmpl

All needed paramaters can be included in this email. You can use same placeholders as in the "REDIRECT URL", which is explained above.

Defining email subject to use when sending upsell request mails. See available placeholder above: 

com.openexchange.upsell.multiple.method.email.subject=


If you like, the upsell plugin can also send an info/advertisement email to ox enduser to inform about upsell after the machine readable mail was sent: 

com.openexchange.upsell.multiple.method.email.oxuser.enabled=


Defining email template to load for ox enduser, if mail to enduser is configured: 

com.openexchange.upsell.multiple.method.email.oxuser.template=

If you need i18n support within email templates, create template with suffix "_<LANGUAGE_CODE>" . Example: /var/upsell_mail_body_ox_enduser.tmpl_de_DE


If you want to use the builtin upgrade methods, you must also configure the OX RMI API informations: 

com.openexchange.upsell.multiple.rmi.host=
com.openexchange.upsell.multiple.rmi.masteradmin=
com.openexchange.upsell.multiple.rmi.masteradmin.pass=

Adding new feature (e.g. video, screenshot)

  • Open register.js (located in gui folder)
  • Search for upsell.config.features
  • add the following code ( description inline )
featurename: {
  name: ["trigger element"],
  title: _("upsell window title"),
  product_name: _("feature headline"),
  intro: _("upsell description text"),
  list: {
    list_item_1:  _("enumeration"),
    list_item_2:  _("enumeration"),
    list_item_3:  _("..."),
  },
  outro: _("upsell text that shows at end"),
  videos: {
    video_1: {
      thumb: "name_of_video_thumbnail.png",
      video: "name_of_video_file.swf"
    }
  },
  images: {
    image_1: {
      thumb: "name_of_image_thumbnail.png",
      image: "name_of_lightbox_image.png"
    }
  },
  buttons: {
    trial: {
      content: _("buttonlabel"),
      action: "put javascript actions here if any"
    },
  },
  checkboxes: {
    invite:{
      content: _("checkboxlabel"),
      action: "put javascript actions here if any"
    }
  }
},
  • after the feature is implemented you should create the nessacarry files and place them as follow
-templates
--_featurename
---- language ( for example de_DE )
-------- flash ( for videos )
-------- img ( for images )


Load required js/cs files

  • to load additional files open register.js and add the following code
upsell = {
  files: {
    jss: {
      name: {
        script: "name.js",
      },
    },
   css: {
     name: "name.css",
   },
 },
}
  • add name.js to jss/name.js
  • add name.css to css/name.css

Change look and feel (e.g. branding, colors and sizes)

  • you should edit the existing css located in /var/www/ox6/plugins/com.openexchange.upsell.multiple.gui/css/upsell.css
  • you can add / edit background in /var/www/ox6/plugins/com.openexchange.upsell.multiple.gui//img


Possible triggers

modules/calendar/freebusy
modules/calendar/team
modules/calendar/mini_calender
modules/calendar/new/add_participants
modules/calendar/new/remove_participants
modules/calendar/new/add_attachment
modules/calendar/new/delete_attachment
modules/contacts/new/add_attachment
modules/contacts/new/delete_attachment
modules/mail/save_to_infostore
modules/infostore/send_as_attachment
modules/infostore/send_as_link
modules/infostore/mail/save_to_infostore
modules/tasks/new/add_participants
modules/tasks/new/remove_participants
modules/tasks/new/add_attachment
modules/tasks/new/delete_attachment
configuration/mail/accounts/new
modules/folders/users

modules/infostore
modules/calender
modules/contacts
modules/mail
modules/portal
modules/tasks
modules/configuration

modules/outlook
modules/mobility
Retrieved from "https://wiki.open-xchange.com/wiki/index.php?title=OX6:OX6-Upsell&oldid=6745"