Oracle Analytics — Troubleshooting Embedded Content
If you’ve found this page, I’m guessing you’re having some issues with getting your embedded Oracle Analytics (OA) project to show properly in your custom webpage or application. This blog will cover some troubleshooting tips and techniques.
Useful Knowledge and Skills
A Summary of the Embedding Process
I thought it would be useful to provide a high level recap of the embedding process . I wrote about how to get started with Oracle Analytics embedding in this blog post. Also, here is the link to the Oracle Analytics product documentation on embedding. In summary, the overall process is as follows:
- Create some content on Oracle Analytics — here are some ideas if you’re just getting started.
- Setup a local development environment. This will consist of a text editor that you’re comfortable using (e.g. Atom or Sublime Text) and has the facility to format code. This is useful to help detect syntax errors.
- You’ll need to test your HTML with embedded Oracle Analytics references within a web server. It’s not possible to just directly open your HTML file in a browser. The quickest and easiest way is to have a localhost web server running on your development machine.
- Enter the domain you’re using for testing and deployment in the Oracle Analytics safe domains page in the Oracle Analytics Console. This is really, really important!
- Create your HTML page and get the reference to the content you want to embed from the ‘Developer’ menu item in the Oracle Analytics project.
- Open your HTML page from your localhost for testing
- Once it looks good, upload to your production web server and tell everyone !
You may have noticed above that I mentioned this was really important! In the majority of cases, this is the cause of the problems you’re seeing when none of the Oracle Analytics visualisations you’ve referenced are appearing. This is usually due to browsers safeguarding against Cross Origin Resource Sharing or CORS.
You may see an error something like:
“AJAX request failed during bootstrap. Request ‘https://<instance>.analytics.ocp.oraclecloud.com:443/ui/dv/ui/api/v1/sessioninfo/ext' response: “
The first thing to check is that you’ve entered the domain that you’re embedding into as an entry in the Oracle Analytics safe domains page in the Oracle Analytics console. You also need to enter the localhost you may be using for development.
The following screen illustrates how this would appear for testing Oracle Analytics embedding into a localhost (also 127.0.0.1) domain that you may be using for developing your embedding HTML page:
Even if you think you’ve already entered the domain, it’s worth double (and triple) checking since there can sometimes be very subtle differences between the domain URL that you log into and the actual domain from where your Oracle Analytics content is located within a web application. This could be the case if you’re embedding into a ‘portlet’ which is a component of a much larger application. You may not even know this until you see an error such as the following within the browser development tools:
“Access to XMLHttpRequest at ‘https://<instance>.analytics.ocp.oraclecloud.com/ui/dv/ui/api/v1/plugins/registry’ from origin ‘https://<this-should-be-in-your-safe-domains>’ has been blocked by CORS policy: No ‘Access-Control-Allow-Origin’ header is present on the requested resource.”
If you’re still seeing an AJAX error, then it may be due to the browser (Chrome or Edge) enforcing SameSite cookies. There is a description, with references to this at the end of this blog, but a quick check can be carried out by putting this in the address bar, e.g. for chrome:
and set the value to ‘disabled’ and retry. If it now works, please log an SR with a description of the problem and we will get your instance updated.
The platform you’re using for development may already have a built in web server that you could use for localhost testing. Alternatively, you could download a web server. The point I want to make in this section is that depending on the web server you use, you may (or may not) have to perform some additional configuration related to CORS (e.g. if you’re using IIS). I’ve seen scenarios where Python was being used as a localhost server and resulting in errors which went away when switching to Node.js.
Just as important as the web server you’re using is the web browser. Ideally your web application will work on any web browser that your users are using to access your website. If you’re seeing errors when testing, there are some things that your browser offers to help troubleshoot. I’m talking about the ‘developer tools’, which depending on the browser in use are accessed in different ways but usually offer very similars tools that are essential to troubleshooting.
The key tools that can help you troubleshoot an Oracle Analytics embed project are:
- Console — this is where you’ll see warnings and errors. Typically they may be related to CORS and can help you know what domain to enter as a safe domain in the Oracle Analytics console (see earlier in this blog for example)
- Network — Ideally you want to see a long list of green 200 status. If you see any 404’s then that can provide further information to help troubleshoot. If you click on the relevant line in the network tab then you’ll see more detail about that particular request and associated headers, response, cookies etc.
- Storage — this can be useful for checking what cookies are created for your webpage and also for clearing any specific cookies when troubleshooting authentication.
- Inspector — as you build your web application, this can be useful for investigating any CSS issues you’re seeing on your page.
- Debugger — as your web page becomes more complex, perhaps making REST API calls, then the debugger is useful to set breakpoints to check everything is functioning as expected.
In some browsers (e.g. Safari), there is a preference to prevent cross-site tracking (this is also on mobile). In some cases when embedding content from Oracle Analytics, you may see an error unless this preference is turned off.
Missing Part of the Filter Bar
If you see the following in the filter bar (appears as a white square) when you embed Oracle Analytics content, then you need to make sure you include the <html dir=”ltr”> tag where the dir will be “ltr” or “rtl” depending on your requirements.
Other Troubleshooting Tips
Directly accessing embedding.js
If you’re having issues with accessing Oracle Analytics, one test you could try is to copy the link from your embedding code directly into your browser’s address bar. The link will be this one, with your instance replaced:
Placement of requirejs calls
In some cases of embedding Oracle Analytics content, there may be implications of what functions are called in the order of when the HTML page is loaded. Note that the Oracle Analytics requirejs calls are placed at the bottom of the page in the <body> section after the <oracle-dv> tag.
Access to the project
If you’re able to authenticate properly but not seeing the expected results, it’s worth checking that the correct path to the Oracle Analytics project / canvas is being used and that the right permissions are set so the project is accessible by the user accessing the custom webpage or application.
If things don’t look as expected, watch out for CSS conflicts (also the use of !important). This can be a consideration if you’re using building a custom web app using a framework.
There is a known issue where you may see the filter bar slightly obscured — this can be worked around by using the following until it’s patched:
position: unset !important;
The relevant section of the Oracle Analytics product documentation : https://docs.oracle.com/en/cloud/paas/analytics-cloud/acubi/embed-visualizations-other-web-pages.html
Note on Chrome versions 80–84
Link to Oracle Support note on this topic (Doc ID 2627621.1)
It’s worth mentioning that the time of writing (March 2020) a recent update to the chrome browser (version 80) has introduced some tighter control over cookies in relation to CORS. We’ve got a change coming that will address this but if you see any errors when embedding Oracle Analytics content that you think are related to this then you can change the chrome setting ‘SameSite by default cookies’ to disabled. Do this by typing chrome://flags in the browser bar and searching on ‘SameSite’.
Update: April 2020 — Latest Update on Chrome 80 — Google is temporarily rolling back Chrome’s SameSite cookie requirements :
Google is temporarily rolling back Chrome's SameSite cookie requirements
With the launch of Chrome 80 in February, Google began gradually rolling out an update that changes how third-party…
Update: July 16 2020 — Chrome is now re-instating the SameSite cookie enforcement :
Link to updates regarding SameSite: https://www.chromium.org/updates/same-site