3.9. Create a New InApp Control

Method URL
PUT oauth2/ctid/inAppControls

Sets up one or more InApp controls in the form of ribbons.

Request Body

Key Required? Data Type Description
brokerCrmName Yes string Please, see Section 2.3.
rules Yes object An object containing the key types of the created InApp control(s).
rules.userId Yes integer The ID of the user to whom the created InApp controls will be displayed.
rules.ribbons Yes array An array containing the main characteristics of the created ribbons. Each ribbon constitutes a separate JSON object.
rules.ribbons.color Yes string The six-digit HEX value of the color assigned to a specific ribbon.
rules.ribbons.title Yes string The text displayed on the ribbon.
rules.ribbons.enabled Yes boolean A boolean value determining whether a ribbon is active (i.e., shown to the user).
rules.ribbons.closable Yes boolean A boolean value determining whether the ribbon is closable by the user. Upon subsequent application launches, all closed ribbons will be re-shown to the user.
rules.ribbons.brokerName No string The name of a specific broker. The ribbon will only be shown to users whose trading account belongs to this broker.
rules.ribbons.ctidTraderAccountId No string The unique ID of the linkage between a specific user and one of their trading accounts.
rules.ribbons.action Yes object An object listing the InApp actions that occur when users interact with the ribbon.
rules.ribbons.action.urlExternal No (but only when using in-app URLs) string The external URL assigned to the relevant InApp action. Upon interaction, opens a separate external browser window.
rules.ribbons.action.urlinApp No (but only when using external URLs) string The in-app URL assigned to the relevant InApp action. Upon interaction, opens an iframe.

Please, note that, as the rules.ribbons array may include several JSON objects (each acting as a unique ribbon), you may combine the above parameters to create custom sets of InApp controls shown under different circumstances. For instance, you may create ribbons that are only shown to users logged in under a specific account; alternatively, certain ribbons may only be shown to users whose current account belongs to a certain White Label (brokerName).

There are three possible cases that may arise depending on the parameters specified in the request body.

  • If a valid ctidTraderAccountId is specified, the ribbon(s) will only be shown to sessions logged in under this specific account.
  • If ctidTraderAccountId is unspecified but a valid brokerName is specified, and there is no ribbon matching by account, the ribbon(s) will be shown to sessions under this specific brokerName.
  • If neither ctidTraderAccountId nor brokerName is specified and there is no ribbon matching by account or brokerName, the ribbons(s) will be shown to sessions under the specified brokerCrmName.

You may also choose to send an empty rules object to immediately clear all ribbons already shown to the sessions specified via other parameters.

Request Example

curl -X PUT ‘https://HOST:PORT/cid/oauth2/ctid/inAppControls?token=04d95575-c9af-42fba72e-2f0ce93f01d4’ -H ‘Content-Type: application/json’ --header ‘Accept: application/json’ -d ‘{"brokerCrmName": "BESTBROKERCRM", "userId": 10345533, "rules": {"ribbons": [{"color": "#ff33ee", "title": "MyRibbon one", "action": {"urlinApp": "https://exampleurl.com"}, "enabled": true, "closable": true, "ctidTraderAccountId": 6530877} {"color": "#33ffee", "title": "MyRibbon two", "action": {"urlExternal": "https://anotherurl.com"}, "enabled": true, "closable": true, "brokerName": "smartBroker"}]}, "userId": 10345533}’

Alternate Example (for clearing ribbons)

curl -X PUT ‘https://HOST:POST/cid/oauth2/ctid/inAppControls?token=04d95575-c9af-42fba72e-2f0ce93f01d4’ -H ‘Content-Type: application/json’ --header ‘Accept: application/json’ -d ‘{“brokerCrmName”: “BESTBROKER”, “userId”: 10335, “rules”: {}}’

Expected Response Status Code

201

Last update: February 6, 2023