Overview

Menu-Items Applications allow you to extend our product by injecting your custom pages and adding new menu items under the existing menu categories.
When clicking the new menu item, we load the app's redirect URL into an iFrame that takes the entire page view.

How does it work?

menu-item applications take several parameters required for displaying additional menu items.
Let's look at an example of such an application structure and then review its elements individually.

Here's a request for creating a new app of type "menu-items:

POST https://api.vcita.biz/platform/v1/apps

Request body:

{
    "name": "{APP_NAME}", // your application name. free text.
    "app_type": ["menu_items"],
    "trusted": true,
    "redirect_uri": "https://your-app-redirect-uri/",
    "url_params": ["business_uid"],
    "menu_items": {
        "subitems": [
            {
                "item_name": {
                    "en": "Playground"
                },
                "route": "my-app-route",
                "category": "calendar",
                "permissions": ["can_access_clients"]
            }
        ]
    }
}

Headers:

{
		"Authorization": "Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

app_type: ['menu_items']

As the name suggests, specifying the app_type as 'menu_items' allows the app to inject new menu items into our platform.
The app_type property accepts an array because applications can have multiple types.

redirect_uri

This is the base URL of your application. It is used for OAuth as described in the OpenID article.
The below meun_item routes relate to this redirect URI. In other words, all additional routes should be children of your app's main redirect URL route.

menu_items: []

The menu_items property is the core of any "menu items" type of app, and it defines the list of desired menu items to be added, along with several parameters that are configured per each menu item:

• item_name: the name or title of the menu item. This would be reflected in the text on the menu item itself and the iFrame's page header.
  The item_name property supports multiple languages. Hence, it accepts an object containing the language as a key and the title (in that language) as a value.
  Currently supported languages on the menu are de, en, es, fr, he, it, pl, pt, ru, sl, tr.
  • The up-to-date list can be found in the Create App API reference, under menu_items\subitems\item_name...
• route: the page route to be opened when clicking the menu item.
  The route is relative to the redirect_uri configured in your app.
  Using this routing mechanism, you can configure multiple menu items under the same app (assuming they represent separate pages of the same app), where each menu item has its own route.
• category: the category (main menu item) under which your new menu item will appear.
  Currently, available categories are: ["calendar", "clients", "payments", "documents", "campaigns", "reputation", "my-livesite", "social", "app_market", "reports", "team-chat", "advertising", "subscriptions"].
  Note that "reports" and "team-chat" will create their main menu item.
  • The Up-to-date list can be found in the Create App API reference, under menu_items\subitems\category.
• permissions: the permissions array defines the permissions needed in order to view the menu item.
  For instance, if a menu item requires the "payments" permission, only users with permission to see payments will also see the menu item, while it will remain hidden from non-permitted users.
  If no permissions are specified, the menu item will be visible for all users.
  Current available permission are: ["can_access_listings_management", "can_access_soci", "can_access_online_presence", "can_access_clients", "can_use_reports", "can_view_payments", "can_view_documents", "has_admin_permissions", "has_marketing_permissions"]
  • The Up-to-date list can be found in the Create App API reference, under menu_items\subitems\permissions.

url_params: ["business_uid"]

The url_params array specifies the list of query params that can be chained to each menu item's URLs.
For instance, your app may need to know the user's role in viewing the app to hide or show some of its features, or maybe it'll need to business uid to pull business info.

Example: https://app.redirect-uri/menu-item-route?business_uid={BUSINESS_UID}

Supported params: ["impersonate", "business_uid", "staff_role", "staff_uid", "payment_permissions", "language", "package", "brand_host"].

You can read a more detailed explanation of each param here.

A reference for the list can be found in the Create App API reference, under _url_params.

Direct links to your app

If you want users to land directly on the page in the business management system, you can link them to the app's route. Use the "brand_host" URL param and "route" you defined to assemble the URL:
https://[brand_host]/embedded/[route]

If you want to send url query parameters to your app use the following format:
https://[brand_host]/embedded/[route]?app_[param_name]=[value]

The new parameters will be added to the above-declared url_parameters. For example:
if you send users to the following URL: https://vcita.com/embedded/myapp?app_id=5 and you asked to have business_uid included in your url_parameters, your application iframe source URL will be: https://yourdomain.com/mylanding_page?id=5&business_uid=1234