Oracle Analytics — Troubleshooting Embedded Content
Updated: April 2024
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
When embedding content from Oracle Analytics, it’s useful to have some knowledge about web development in general. If you’re looking for a starter list of skills then it’s worth reading up on HTML, CSS, JavaScript, CORS and becoming very familiar with the development tools that are offered in web browsers. I’ll write more about how to use the browser tools specifically to troubleshoot Oracle Analytics embedding later in this blog.
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) or VS Code is also a good option. Editors that have the ability to format code 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. The Live Server extension to VS Code is worth trying.
- 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!
- Make sure that you have checked ‘Enable Developer Options’ in the profile section or you won’t the the ‘Developer’ menu option used in the next step.
- 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 !
Safe Domains
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 (on port 8080) domain that you may be using for developing your embedding HTML page:
You don’t need to check all the boxes.
If you’re using the compatibility mode option for the <oracle-dv> embedding tag, you may also need to check ‘Allow Frames’ if you don’t see your embedded content.
This configuration page in Oracle Analytics determines the content security policy (CSP) that is sent to the web browser so ensuring you only select the boxes that are needed will keep network traffic to a minimum.
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 or a difference between a development and runtime URL for a web based IDE.
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:
chrome://flags/#same-site-by-default-cookies
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.
Web Server
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.
Browser
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 referring to the ‘developer tools’, which depending on the browser in use are accessed in different ways but usually offer very similar 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.
Browser Preferences
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.
Browsers Blocking 3rd Party Cookies
Chrome is phasing out support for 3rd party cookies. This can impact on your embedding experience since Oracle Analytics uses cookies for authentication and when embedded into another website, these cookies can be deemed 3rd party and thus blocked. The easiest way to make things work in this scenario is to use a vanity URL.
Mixed Mode or Content
When developing or testing a website with embedded analytics, as mentioned earlier, it’s likely that you’ll be using a localhost webserver that may not use TLS (i.e. urls start with https, previously known as SSL). If you’re working with Oracle Analytics Server (OAS), then it may (or may not) use TLS but Oracle Analytics Cloud (OAC) will always use TLS (i.e. you will access OAC on a URL that starts https). This is important since web browsers, may not show embedded content when ‘Mixed Mode or Content’ is present — i.e. a localhost server, no TLS, embedding OAC content from a TLS https url. In some cases, it’s possible to enable this with a browser configuration setting, but it’s important to be aware of this scenario if you don’t see the embedded analytics content appear.
Compatibility Mode
There are certain scenarios where you may need to include embedded analytics content in an iFrame two examples are where there may be a different major version of Oracle JET in use on the hosting page (e.g. an Oracle Visual Builder or APEX application) to the version of Oracle JET that Oracle Analytics is using. There may also be other cases, e.g. a CSS clash that may require the embedded analytics to be ‘sandboxed’ using an iFrame. The compatibility-mode setting of the <oracle-dv> embedding tag can be used in these scenarios, by automatically creating an iFrame at runtime, with options to always create the iFrame or only if a different major version of Oracle JET is detected on the host page.
Other Troubleshooting Tips
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.
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:
https://<instance-name>.analytics.ocp.oraclecloud.com/static/dv/embedding/v1/standalone/embedding.js
The result you should see will be a page of JavaScript code without the need to authenticate.
Note that you cannot download ‘embedding.js’ to reference this file locally as it is dynamically generated content.
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.
CSS Issues
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:
<style>
.bi_filterbar_padding_left{
position: unset !important;
}
</style>
References
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 :
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
