Embedding RubiqCloud Profile
This document describes how RubiqCloud Profile may be integrated into any web-based system using an IFRAME or by opening a browser instance
1. Generate an access token from the Rubiq API
In order to access data in RubiqCloud, it is necessary that a security token is attached to each URL that is iframed or opened. This token can be generated via the following API endpoint: https://rubiqsoft.atlassian.net/wiki/spaces/RESTAPI/pages/2686582785/6100+Generate+access+token
Documentation on how the Rubiq API is used can be found here: https://rubiqsoft.atlassian.net/wiki/spaces/RESTAPI/pages/524620/Authenticating+requests
Authenticating request requires an AppKey and an AppSecret. These are provided by Fluid on request.
Please note that a token has a limited lifetime. In the response returned from the API, the lifetime is specified in the expires property.
Token protection is not a requirement, but is nevertheless highly recommended. As an alternative to token protection, an embedding can also be locked to one or more IP addresses. IP address locking can also be used in conjunction with token protection.
2. Construct the URL for the IFRAME
An embeding needs to know which profile in RubiqCloud to display, and the profile can either be specified directly using the Rubiq ID, or using one of the key types configured in addition to the Rubiq ID. Examples of other key types could be email address, CRM ID, contact number, etc. The format of the URL depends on whether the lookup is done using Rubiq ID or a key type.
Lookup using Rubiq ID:
https://{subdomain}.rubiq.net/embedding/{embeddingID}/profile/{rubiqID}/token/{token}
Lookup using a key type:
https://{subdomain}.rubiq.net/embedding/{embeddingID}/profile/{keyID}/{keyValue}/token/{token}
Variables in URL
Variable | Value |
|---|---|
subdomain | TEST: {cloud-name}.test PROD: {cloud-name} |
embeddingID | A unique ID identifying the embedding to display. An embedding holds preconfigured settings and access grants. Please note that the ID will differ between test and production. |
keyID | Integer value RubiqCloud can hold any number of unique keys for a contact, and each key has its own key ID. Depending on the setup of the cloud instance, keys could be email address, CRM ID, Contact number and so on. |
rubiqID | Rubiq ID to lookup |
keyValue | Key value to lookup, for instance email address, CRM ID and similar |
token | The access token generated from the Rubiq API endpoint described above. This variable may be omitted if IP address locking is used instead of token security. |
Example 1
Assuming that email address is a key identifier in RubiqCloud with key ID 1, you could lookup john@doe.com in the test environment for cloud instance acme, assuming that Rubiq has generated an access token with value A12345
https://acme.test.rubiq.net/embedding/1c6e5108-bd41-4813-beb1-0f00f58bb285/profile/1/john@doe.com/token/A12345
Example 2
Assuming that CRM ID is a key identifier in RubiqCloud with key ID 2, you could lookup CRM ID 45892738 in the production environment for cloud instance acme, assuming that Rubiq has generated an access token with value A12345
https://acme.rubiq.net/embedding/1c6e5108-bd41-4813-beb1-0f00f58bb285/profile/2/45892738/token/A12345
3. Optional filtering by tags
An embeding may be configured to filter its display based on tags. In that case, filtering can be controlled using the URL argument rbq-tags. The value of the argument is expected to be a comma-separated list of tag IDs. Tag IDs can be found using the RubiqCloud user interface and are typically a GUID.
Example
Looking up a profile with Rubiq ID 159753654 on cloud instance acme, using embedding 1c6e5108-bd41-4813-beb1-0f00f58bb285 and a token value of A12345, we can filter the display by tag ID d4ba257c-888e-4b12-8626-7947f2a93771 with the following URL
https://acme.rubiq.net/embedding/1c6e5108-bd41-4813-beb1-0f00f58bb285/profile/159753654/token/A12345?rbq-tags=d4ba257c-888e-4b12-8626-7947f2a93771
4. Optional transfer of context data
Updates and actions performed on a profile lookup in an embedding can be enriched with contextual data. For example, contextual data can contain important information about the person who performed the action. Any URL argument placed in the URL to the embeding that does not begin with rbq- will be considered contextual data.
Example
We want to store shop and employee ID so that we can track where a given action was taken from. The shop ID should be stored as context data field "shopID" and the employee ID should be stored as context data field "empID".
https://acme.rubiq.net/.../?shopID=172&empID=9513578246
(The complete specification of embedding ID, Rubiq ID and token is omitted to make it easier to identify the relevant URL arguments.)