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 validbrokerName
is specified, and there is no ribbon matching by account, the ribbon(s) will be shown to sessions under this specificbrokerName
. - If neither
ctidTraderAccountId
norbrokerName
is specified and there is no ribbon matching by account orbrokerName
, the ribbons(s) will be shown to sessions under the specifiedbrokerCrmName
.
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