This document is a draft / work in progress as this API is still in development. Please contact us, if you would like to begin using this API.

About Apps API

Mozello Apps API allows to place your app in the Mozello Apps catalog (formerly known as Extras). This API should be used in conjunction with other Mozello APIs, especially Store API.

For example, if you have an accounting app that integrates with Mozello using Store API, you can now prominently show your app in the Mozello Apps catalog and provide an easy one-click install.

Server-Side API

Basics

The base URL for all API calls is https://api.mozello.com/v1/

For Apps, authCode query parameter must be added.
https://api.mozello.com/v1/?authCode=xxxxx
You will obtain authCode during installation process.

API calls are made to the corresponding API URL which, in turn responds with a JSON object. Optional properties might be omitted or returned as null. The returned HTTP status will be 200 for successful or partially successful API calls, and 4XX or 5XX for unsuccessful API calls.

GET, POST, PUT and DELETE HTTP methods are used for standard API methods that perform Get, Create, Update and Delete actions with a resource. POST HTTP method is used for non-standard methods.

Payloads are in JSON format.

For authentication API key must be sent in an HTTP header of each request:

Authorization: ApiKey MZL-d4fcd4c02c88eafaeaef7f87f6796f12

Example

Request (raw HTTP)

GET /v1/apps/languages/?authCode=xxxxx HTTP/1.1
Host: api.mozello.com

Success response

{
    "error": false,
    "languages": ["en", "de", "fr"]
}

Error response

{
    "error": true,
    "error_code": 401,
    "error_message": "Unauthorized"
}

Mark as installed

POST /apps/installed/ - mark app as installed.

Marks installed app instance as finished installing. This method must be called to finish the app installation process.

Parameters

none

Uninstall

POST /apps/delete/ - uninstall app.

Uninstalls app from the website. Uninstalling app will clear all app snippets and data.

Parameters

none

Set code snippet

POST /apps/set_snippet/ - set HTML code snippet.

Sets code snippet to be included in HTML body of every page or only pages in specified language, if language parameter used.

Parameters

  • snippet - string.
  • language - string, optional - language code.

Example

Set code snippet:

{
    "snippet": "<script src='//example.org/examplescript.js' type='text/javascript'></script>"
}

Get code snippet

GET /apps/get_snippet/ - get HTML code snippet.

Gets current code snippet set by set_snippet API call.

Example return data:

{
    "snippet": "<script src='//example.org/examplescript.js' type='text/javascript'></script>"
}

Get code snippet for language

GET /apps/get_snippet/<language>/ - get HTML code snippet for language.

Gets current code snippet set by set_snippet API call for specified language.

Example return data:

{
    "snippet": "<script src='//example.org/examplescript.js' type='text/javascript'></script>"
}

Set data

POST /apps/set_data/ - set configuration data.

Sets data for the installed app instance. Any user configuration for the app can be stored here.

Parameters

  • data - string/object.

Example

Set data:

{
    "data": {
        "example_property_1": "Example",
        "example_property_2": "Example"
    }
}

Get data

GET /apps/get_data/ - get configuration data.

Gets data set by set_data API call.

Example return data:

{
    "data": {
        "example_property_1": "Example",
        "example_property_2": "Example"
    }
}

Get user info

GET /apps/user/ - get user info.

Gets basic user info.

Example return data:

{
    "user": {
        "email": "example@example.org",
        "email_confirmed": false
    }
}

Get website info

GET /apps/website/ - get website info.

Gets basic website info.

Example return data:

{
    "website": {
        "url": "https://www.example.org/",
        "brandname": "example"
    }
}

Get website languages

GET /apps/languages/ - get website languages.

Gets list of languages used in the website.

Example return data:

{
    "languages": ["en", "de", "fr"]
}

Code Snippets

Basics

It is common for an app to add a code snippet to the website's head or body to enable the app's JavaScript features. This can be done in the following ways:

The default snippet set by the manifest is used for all websites that have the app installed. The Set Code Snippet function will overwrite it for the specified website. Set Code Snippet with a language code specified will overwrite it further for the pages in the specified language of the specified website.

It is recommended to use the default snippet whenever possible as it makes updating the snippet easy. Modifying it will change it for all websites, and the updated snippet will appear in the published websites as soon as the individual website cache expires.

Code snippets support the following placeholders:

  • {{moz_app_data}} - insert data set by Set Data API function
  • {{moz_language}} - insert language code

Example Code Snippet:


<script type="text/javascript" src="https://my-app.example.org/my-script.js" defer></script>
<script>
$(document).ready(function() {
    myInitializationSample({
        all_settings: {{moz_app_data}},
        language: {{moz_language}}
    });
});
</script>

Head snippets will be inserted into the <head> block, and other snippets into the page <body>.

It is important that any HTML manipulation by scripts is performed after the document is ready. The recommended way to achieve this is to use jQuery document ready event.

Client-Side JavaScript API

Basics

The Client-side JavaScript API allows your application to react to website events and visually enhance specific parts of the website by inserting custom HTML.

Custom content insertion works as follows:

  1. Subscribe to an event from your app's client side code, using subscribeEvent.
  2. Pass a callback function as subscribeCallback parameter. It will be fired, when content can be inserted.
  3. From within the callback function create contentHandler object that deals with inserting the content.
  4. Call contentHandler.setContent to insert content (HTML code).

Client-Side Events

Use the mozPlugins.subscribeEvent(eventName, subscribeCallback) function to subscribe to an event. The subscribeCallback parameters are (event, initContentHandler, eventParam, [updatedItem]):

  • event - DOM event
  • initContentHandler - function that your subscribeCallback must call to obtain the contentHandler
  • eventParam - event parameter object
  • updatedItem - for "update" events only, an object containing dynamically changed data

The contentHandler returned by initContentHandler() is an object with the following properties:

  • setContent - callback for setting/updating content related to the event. Parameters: contentHandler.setContent(htmlCode)
  • params - event parameter object

Some events come in pairs: event-name and event-name-updated. The "updated" event is triggered if dynamic changes in the page might require updating the inserted HTML.

var afterPriceContentHandler;

mozPlugins.subscribeEvent('moz-content-after-price', function(event, initContentHandler, eventParam) {
    afterPriceContentHandler = initContentHandler();
    afterPriceContentHandler.setContent('Hello from plugin!');
});

mozPlugins.subscribeEvent('moz-content-after-price-updated', function(event, initContentHandler, eventParam, updatedItem) {
    if (afterPriceContentHandler) {
        afterPriceContentHandler.setContent('Hello from plugin! (product updated)');
    }
});

Note: You should call initContentHandler() early in the subscribeCallback, but you can call contentHandler.setContent later, in case obtaining the data to insert takes time (e.g., a server request is required).

Note: You should call initContentHandler() no more than once for each event. If you're using the event-name and event-name-updated pair, only call it in the subscribeCallback of the event-name subscription.

Custom content in product page

Event names:

moz-content-after-price
moz-content-after-price-updated

Allows adding dynamic content in the product page next to the price. Subscribe to moz-content-after-price-updated if the content depends on the user-selected product variant and its attributes such as price, weight, and others.

Parameters:

  • eventParam - object:
    • item - object containing product information
    • page - object containing page and language information
  • updatedItem - object:
    • item - object containing product information
    • selectedVariant - object containing selected variant information. The variant can override product attributes such as price, weight, etc.
    • selectedVariantId - ID of the selected variant

Custom content in cart

Event names:

moz-content-after-cart

Allows adding dynamic content below the cart items list.

Parameters:

  • eventParam - object:
    • cartData - object containing cart information
    • currency - currency in the display format
    • page - object containing page and language information

Custom content in checkout page

Event names:

moz-content-after-checkout
moz-content-after-checkout-updated

Allows adding dynamic content in the checkout page below the checkout items list. Subscribe to moz-content-after-checkout-updated if the content depends on the total checkout price, as it can change when the discount code is applied.

Parameters:

  • eventParam - object:
    • cartData - object containing cart information
    • currency - currency in the display format
    • page - object containing page and language information
  • updatedItem - contains the updated cartData

Creating App

Basics

To create Mozello App, the following steps need to be taken:

  • App must be hosted on your web server. HTTPS (SSL) connecton is mandatory. App must interact with Mozello websites via API (Apps API, Store API).
  • App manifest must be created and submitted to App integration setup portal, to be added to Mozello Apps catalog.
  • App must support Mozello App installation process, to allow Mozello users to install the App to their website.

The integration process

This process will add your App to Mozello Apps catalog and assign API key for your App.

The process:

  1. Create a Mozello account for testing
  2. Submit your integration manifest via App integration setup portal and receive your API key
  3. Implement Mozello App installation process for your App
  4. Submit your integration for approval via App integration setup portal
  5. Upon successful approval, your integration will go live
  6. Update your integration details via App integration setup portal any time
  7. Re-submit modified integration details for approval via App integration setup portal

Please keep your API key secret and prevent any possible public access to your API key.

App manifest

Submit a structured data manifest (in JSON format) containing information about your App.

Upon signing up and submitting the manifest, you will receive a secret key that App must use for API authentication.

Manifest example

{
    "app_type": "APP",
    "app_title": "Hello World",
    "app_icon": "https://www.example-app.org/icons/app.png",
    "app_version": "1.0.0",
    "app_description_short": {
        "en": "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
    },
    "app_description_full": {
        "en": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque pretium nulla a tincidunt hendrerit. Nullam lacinia, leo quis vestibulum pretium, mauris metus laoreet sem, vitae bibendum justo eros porta neque. Praesent semper sit amet magna bibendum convallis. Proin non lorem id enim imperdiet maximus sed ut turpis."
    },
    "app_screenshots": {
        "en": "https://www.example-app.org/icons/screenshot.png"
    },
    "app_vendor": {
        "company_name": "Company",
        "support_email": "support@example.org",
        "support_phone": "+1 555 0101 1234",
        "developer_email": "developer@example.org",
        "company_url": "https://www.example-app.org",
        "support_url": "https://www.example-app.org/support/",
        "privacy_url": "https://www.example-app.org/privacy/",
        "tos_url": "https://www.example-app.org/tos/"
    },
    "app_permissions": ["FULL"],
    "app_tab_mode": "blank",
    "app_install_url": "https://www.example-app.org/install.php",
    "app_settings_url": "https://www.example-app.org/settings.php",
    "app_secret": "RYdabN4UPtjG2YJMxJGX1qhRKTexBgMf"
}

Manifest reference

* denotes mandatory fields

  • app_type * - always APP
  • app_title * - title of App, non-localizable string
  • app_icon * - link to App icon image, square, at least 80 x 80 px
  • app_version * - version number in format x.x.x
  • app_display_title - string or languages object, use if your title is localizable
  • app_description_short * - string or languages object, text must be very brief
  • app_description_full * - string or languages object
  • app_screenshots - string or languages object, links to images, one screenshot per language
  • app_vendor * - info about the App developer
    • company_name * - name of representing company
    • support_email * - support e-mail, string or langages object
    • support_phone * - support phone number, string or languages object
    • developer_email * - e-mail for informing about critical and breaking API changes
    • company_url * - link to company website, string or languages object
    • support_url * - link to App support website, string or languages object
    • privacy_url * - link to Privacy Policy page, string or languages object
    • tos_url * - link to Terms of Service page, string or languages object
  • app_permissions * - always ["FULL"]
  • app_tab_mode * - blank or self. Use blank to open your App in new tab or self for the same tab
  • app_install_url * - link to App installation process initialization
  • app_settings_url * - link to App configuration, management or main panel
  • app_default_snippet - default code snippet to insert in <body> of websites that install the App.
  • app_default_head_snippet - default code snippet to insert in <head> of websites that install the App.
  • app_default_snippet_source_url - loads snippet code from the URL and inserts it into app_default_snippet. Overwrites app_default_snippet.
  • app_default_head_snippet_source_url - loads snippet code from the URL and inserts it into app_default_head_snippet. Overwrites app_default_head_snippet.
  • app_secret * - secret string used for verifying App requests from Mozello; think of this as a password, it is made up by you, you can use something you can easily remember or a random string

Implementing App installation

When Mozello user installs App to their website, they will get redirected to your App installation link (app_install_url). Your App must perform specific steps to complete the installation process successfully.

Mozello Payment API

Steps:

  1. Prerequisite: App must be added to Mozello App catalog
  2. User clicks Install button in Mozello app catalog
  3. Mozello redirects browser to installation link (app_install_url from manifest)
  4. App must verify the request hash
  5. App must use URL from the callback parameter and add all GET parameters except callback and hash to obtain redirect link back to Mozello infrastructure, then execute the redirect.
    Example
    For request link:
    https://www.example-app.org/install.php?callback=https%3A%2F%2Fcallback-domain.org%2Fhelloworld%2F%3Fhash=12345abcd&appId=1234567890&language=en
    Corresponding Mozello installation initialization link is:
    https://callback-domain.org/?appId=1234567890&language=en
  6. User must review the App permission request screen and click Accept.
  7. Mozello redirects browser to installation link again but this time authCode parameter is set. You will need authCode to call API functions. If your App has users, you can associate authCode with the user.
  8. App must verify the request hash again.
  9. App must use installed method from Apps API to finish the installation process.
  10. App can be displayed. Alternatively, redirect back to Mozello (only for Apps with app_tab_mode set to self). To redirect user back to Mozello, use callback parameter and add all GET parameters except callback and hash to obtain redirect link, then execute the redirect.

Request parameters

  • hash - must be used to verify request authenticity
  • authCode - code that specifies the Mozello App installation instance and must be used for Apps API authentication
  • appId - Mozello App ID in Mozello Apps catalog
  • language - preferred UI language for user
  • callback - link for returning to Mozello
  • mozelloVersion - Mozello frontend version number

Implementing App configuration

For already installed App, user can click Settings button. This will open settings link, which should point to App configuration, management or the main panel of the App.

For this request authCode parameter is included, which lets your App know that the user has been authenticated with Mozello and if you associated this authCode with user in your App during installation, you can log in the user automatically.

Steps:

  1. User clicks Settings button in Mozello App catalog
  2. Mozello redirects browser to app settings link (app_settings_url from manifest)
  3. App must verify the request hash
  4. App settings GUI can be displayed. Use Apps API or Store API where appropriate to interact with Mozello website

Request parameters

  • hash - must be used to verify request authenticity
  • authCode - code that specifies the Mozello App installation instance and must be used for Apps API authentication
  • appId - Mozello App ID in Mozello Apps catalog
  • language - preferred UI language for user
  • callback - link for returning to Mozello
  • mozelloVersion - Mozello frontend version number

Verifying request authenticity

Installation and settings requests must be verified to ensure that they are coming from Mozello.

The hash is computed by running a sha256 HMAC hash function on the query string of the request for all parameters except hash. Use app_secret specified in App manifest as hash function key.

Pseudo code for generating signature

query_string_truncated = remove_parameter("hash", query_string)
signature = HMAC_SHA256(query_string_truncated, secret)

PHP example for validating request

if (isset($params['hash'])) {
    unset($params['hash']);
}

$params = http_build_query($params);
$calculatedHash = hash_hmac('sha256', $params, $secret); // $secret is app_secret from app manifest

// check if hash matches
if ($hash == $calculatedHash) {
    // Your code here
}

Sample source code

This sample demonstrates the basic framework for App and implements the installation, configuration and verification steps described above: mozello-sample-app-hello-world on GitHub