Wialon for developers User guide API reference apps create

create

To add an app to the service, use the apps/create method. The added app appears in the Apps list in CMS Manager.

Only the top user of the service can use this method in Wialon Hosting.

Endpoint

Copied!

svc=apps/create&params={
  "name": <text>,
  "description": <text>,
  "url": <text>,
  "flags": <uint>,
  "langs": <text>,
  "sortOrder": <int>,
  "requiredServicesList": <text>,
  "billingPlans": <text>
}

Parameters

The request must contain all the following parameters. If a parameter isn’t required for your app, specify an empty value for it ("" for text parameters and 0 for numeric ones).

Parameter	Description
name	App name. It can’t be empty.
description	App description. It’s also used as the description of the app service. You can leave it empty.
url	URL where the app is hosted. It must start with `http://`, `https://`, or `//`.
flags	App flags (advanced URL parameters). For the possible values, see Flags. Use `0` if you don’t need any of them.
langs	Languages of the interface for which the app is available, separated by commas, for example, `"en,ru"`. If the value is empty, the app is available for all languages.
sortOrder	Sort order of the app in the list.
requiredServicesList	Names of the services required for the app, separated by commas. Each service must be available in your account. Don’t add a comma at the end of the list. You can leave it empty.
billingPlans	Names of the billing plans for which the app is available, separated by commas. Each billing plan must exist in your service. You can leave it empty.

For more information about the app parameters, see Apps.

Flags

The flags parameter defines which parameters are added to the app URL when a user opens the app. Each flag matches an option of the Advanced URL parameters section in CMS Manager. To combine several flags, add up their values. For example, the apps from the library use the value 31 (0x1F): 0x1 + 0x2 + 0x4 + 0x8 + 0x10.

Value	Option in CMS Manager	Parameter added to the app URL
`0x1` (1)	Active SID	`sid=<session ID>`. Authorization by session ID: the user stays logged in to the app after a page refresh.
`0x2` (2)	Current user	`user=<name of the current user>`.
`0x4` (4)	Base URL	`baseUrl=<API address>`, for example, `https://hst-api.wialon.com`.
`0x8` (8)	Host URL	`hostUrl=<address from which the user opened the app>`, for example, `https://hosting.wialon.com`.
`0x10` (16)	Language	`lang=<interface language of the current user>`.
`0x20` (32)	Authorize hash	`authHash=<hash>`. Authorization by hash created using the core/create_auth_hash method: the user is logged out of the app after a page refresh.

For users to be able to log in to the app, specify the 0x1 (Active SID) or 0x20 (Authorize hash) flag.

When you create an app, the system also does the following:

creates the app.<serviceName> service in your account (the Display in menu: service in CMS Manager);
adds this service to the billing plans specified in the billingPlans parameter.

Example

Copied!

svc=apps/create&params={
  "name": "My app",
  "description": "",
  "url": "https://example.com/app",
  "flags": 31,
  "langs": "",
  "sortOrder": 0,
  "requiredServicesList": "",
  "billingPlans": ""
}

In this example, the 31 flag value adds the sid, user, baseUrl, hostUrl, and lang parameters to the app URL. For details, see Flags.

Response

If the request is completed successfully, the response is returned in the following format:

Copied!

[
  <long>,   /* App ID */
  {
    "name": <text>,                  /* App name */
    "description": <text>,           /* App description */
    "url": <text>,                   /* App URL */
    "flags": <uint>,                 /* App flags */
    "sortOrder": <int>,              /* Sort order */
    "serviceName": <text>,           /* Name of the app service without the "app." prefix */
    "id": <long>,                    /* App ID */
    "langs": <text>,                 /* Languages of the interface */
    "requiredServicesList": <text>,  /* Required services */
    "billingPlans": <text>           /* Billing plans */
  }
]

If the request fails, an error code is returned.

Error codes

Error code	Description
4	Wrong input parameters, or one of the parameters is missing.
7	Access denied: the user isn’t the top user of the service, or the service isn’t Wialon Hosting. This code is also returned if the name or URL is incorrect, a required service or billing plan isn’t available, or the app can’t be created.

If you find a mistake in the text, please select it and press Ctrl+Enter.