Embedding Oracle Analytics in APEX for Mobile

There are a number of benefits to combining Oracle Analytics (OA) with APEX and I’ve previously written about how to embed OA with APEX. In this blog, I’ll describe three areas that will ensure your embedded analytics content works in an APEX application when used on a mobile device. These are

1. Use the same domain between the OA and APEX instances
2. Using token authentication for the embedded OA canvases
3. Defining a responsive layout for the analytics canvas.

Same Domain

Web browsers are starting to block third party cookies, although at the time of writing, this appears to becoming an optional user setting in Chrome, similar to Safari and Firefox browsers. This can potentially cause issues when you’re embedding content from an analytics instance that is on a different domain to an APEX application (even if safe domains have been configured). The domain for analytics might be <name>.oraclecloud.com while the domain for APEX might be <name>.oraclecloudapps.com. This can be a particular issue on mobile devices, such as an iPhone, as the Safari browser has a setting ‘prevent cross site tracking’. While it’s possible to disable this setting temporarily for testing purposes, you wouldn’t expect your users to keep it disabled.

The way to work with these browser settings and cookies being blocked is to use a ‘vanity URL’. As an example, let’s say you own the domain ‘analytic-apps.com’ then you would configure an Oracle Analytics vanity URL of ‘oac.analytic-apps.com’ and an APEX vanity URL of ‘apex.analytic-apps.com’. Details of configuring a vanity URL for analytics can be found here and this video describes the configuration of a vanity URL for APEX, using the OCI load balancer service. In both cases, you’ll require certificates for the subdomains and the ability to configure DNS entries for the domain.

Token Authentication

If you’re new to OAuth2, I’ve written an introduction to the topic related to Oracle Analytics, in addition, I’ve also written on how tokens can be used to authenticate an embedded analytics canvas (the scenario was a ‘public’ use case, but the mechansim to use a token for authentication is also the same for non-public use cases).

If you are embedding Oracle Analytics into an APEX application, it’s recommended that you configure the APEX application to use Oracle IDCS/IAM for authentication. This should be the same IDCS/IAM that Oracle Analytics is using as it’s authentication provider. If it is the same IDCS, then you also have authentication options such as 3-legged, since you’d be using the same user population for both analytics and APEX. The 3-legged option for embedded analytics, essentially looks for existing cookies that are created when a user authenticates. Note: make sure to also add the domain of the analytics instance to it’s own safe domains list (select the Allow Frames and Embedding options) if you’re having any issue with the 3-legged configuration embedding into an iFrame.

Obtaining a token

The most reliable way to authenticate embedded analytics content is to use tokens. Assuming you’ve configured your APEX application to use IDCS/IAM for authentication, there are some additional configuration steps to ensure you get a token that can be passed to the embedded analytics.

As part of the configuration, you’ll have registered a confidential app in IDCS/IAM. The first additional step, is to map the Analytics instance as a resource in the OAuth configuration of the confidential application. This is achieved by using the ‘Add Scope’ button in the ‘Resources’ section of the OAuth configuration screen. You need to find the analytics instance in the list of resources that are shown, the name will start with ‘ANALYTICSINST_’. Once you have mapped that instance as a resource, make a note of the scope.

This will be something like:
https://<ListOfCharacters>.analytics.ocp.oraclecloud.comurn:opc:resource:consumer::all

The next step is to configure the APEX application, shared components, Authentication Schemes and edit the scheme configured for IDCS/IAM to add the scope (noted earlier) to the ‘Scope’ field in the settings. Note that this isn’t the URL of the analytics instance but the scope as copied earlier, when you mapped the instance in the confidential app.

In the example below, the scope field contains the following:
profile,groups,https://<obfuscated>.analytics.ocp.oraclecloud.comurn:opc:resource:consumer::all

APEX Authentication Scheme Settings — Analytics instance scope added

Check the expiry time for the token. The default for Oracle Analytics is 100s so you’ll want to increase this to something longer e.g., 3600s. You can change this by searching for the analytics instance (name starting with ‘ANALYTICSINST_’) in IDCS/IAM in the section ‘Oracle Cloud Services’, then editing the OAuth Configuration, the Access Token Expiration setting is found at the top. For consistency, you could also set the equivalent APEX session length so when the token expires, the user has to re-authenticate.

When an APEX application is configured for IDCS/IAM authentication, the user is prompted to login using the ‘Authorization Code’ grant type. This process returns JSON to the APEX application that contains a number of fields, including an access token that can be mapped to e.g., an APEX application item ‘ACCESS_TOKEN’ using the following code in a post authentication procedure. Typically, your post authentication procedure may already be obtaining group membership so you’d add the line to any existing code.

procedure get_access_token as

begin

APEX_SESSION_STATE.SET_VALUE('ACCESS_TOKEN', apex_json.get_varchar2( 'access_token'));

end;

Using the access token

In order to add embedded analytics content to an APEX application page, add a static region to the page and the following code to the HTML source, replacing the project path and active-tab-id according to the specific references in your own instance:

<div id='embedArea' style='width: 100%; height: 600px'>
    <oracle-dv 
        project-path='/@Catalog/shared/APEX VANITY/Top10 Product Orders'
        active-page='insight'
        active-tab-id='snapshot!canvas!1'
        parameters='{{parameters}}'
        project-options='{"bDisableMobileLayout":true, "bShowFilterBar":false}'>
    </oracle-dv>
</div>

In this example, we will be using an APEX selector to select a value for order status and then pass that selection onto the embedded analytics canvas via a parameter mapped to a filter.

In order to make the token available on the page, create a hidden page item of type static value (e.g. P7_TOKEN) and map the source to the APEX application item: ‘ &ACCESS_TOKEN.’ I have this set to:

Used: Always, replacing any existing value in session state

and the session state of Per Session (Persistent).

At the APEX application page level, add the following in the JavaScript section. Note the use of the /jet/ path for embedding.js since JET is available with APEX.

File URLs

[require jet]
https://<OAC-Instance>/public/dv/v1/embedding/jet/embedding.js

Function and Global Variable Declaration

In this section, the token is passed to a JavaScript variable ‘vToken’ for use with the embedded canvas. The value selected by the user is also passed to a JavaScript variable ‘vORDER_STATUS’ that is referenced for the ‘p1v’ parameter value.

vToken = apex.item("P7_TOKEN").getValue();
vORDER_STATUS = apex.item("P7_SELECT_ORDER_STATUS").getValue();

Execute when Page Loads

This section contains the knockout JS model and observable definitions for the parameters that are used in the <oracle-dv> embedding tag as well as the passing of the token to authenticate the embedded analytics canvas.

requirejs(['jquery','knockout', 'obitech-application/application', 'ojs/ojcore', 'ojs/ojknockout', 'ojs/ojcomposite', 'jet-composites/oracle-dv/loader'],
    function($, ko, application) {

        function model() {
                   var self = this;
                   self.parameters = ko.observable({
                                     'p1n': 'pORDER_STATUS',
                                     'p1v': vORDER_STATUS});
                  };

        application.setSecurityConfig('token', {tokenAuthFunction:
            function(){
                return vToken;
                }
            });

        ko.applyBindings(new model);

            });

The expected behaviour, with these components in place, is that a user logs in to the APEX application. A token is passed back from IDCS/IAM (accessible from apex_json in the post-authentication procedure). That token is obtained on the page(s) that include embedded analytics and is used to authenticate that embedded content.

Responsive Layout

A key aspect of viewing embedded content on a mobile device is how it appears on a smaller screen, or even differences in screen size if the same application is used across various devices. In order to allow embedded analytics to be optimally viewed, a feature called responsive canvas layout allows the definition of canvas layouts for various screen widths.

The following video explains how to define responsive layouts:

When using the responsive layout with embedded Oracle Analytics, with the <oracle-dv> JavaScript embedding framework, ensure that you use the configuration option as follows or you may see the default mobile ‘stacked’ view on mobile devices.

project-options='{"bDisableMobileLayout":true}'

Summary

This blog has described three key aspects of configuration and implementation to ensure your APEX applications with embedded analytics work smoothly on mobile devices.