Managing Image URLs in OGL Design Kits

Why avoid Base64 Image URLs

You may have recently encountered a problem with accessing the OGL Console by any of the users. This may have resulted after you have made some recent changes to your OGL Design Kit in the OGL > Settings > Theme section. This issue is caused by custom images that were embedded as Base64 strings in themes, which is not a recommended practice, as it may cause:

  • Session storage overflows (exceeding 5MB browser limits).
  • Performance degradation (slow loading, poor caching).
  • Maintenance challenges (hard to read/update long strings).

Best Practice: Do not use Base64 image strings. Instead, use hosted URLs for images/icons.

Step‑by‑Step Instructions

Step 1: Upload Images to OCI Bucket (Default provided by OGL) In this example, suppose you wish to upload the following image to your OGL Design Kit:


Logo

  1. From the OGL console, create or edit a guide and add the image (i.e. Copy/Paste) directly into a tooltip. Once pasted, double-click the image to open the Image Properties dialog.


    Image Properties

    Notice that the image URL has been automatically converted to a Base64 URL text string like this:
    data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIAAAAxCAIAAAAXyW1IAAAChElEQVR4AeyWTUiUURSGw4QW4wQGEdIiaGCiIKEyKDdGC9tEEa2iqFUgLRO3ybTMdBlT7frBVQjRpoLIjQYVRUGLgREEyURI6A+MFj3y2iV/OPeecSNy5Xo43/3ec+5733vm3K9pvLtjHY6mTevyL9PyHEtWK6vlUcCDzbWV1fIo4MHm2spqeRTwYDdEbTW3FLe2Hyr19u+/9bDj0YsjT1/b48C9x+X+ge3dJz1KLWAdakFo743qvoEqyxRKZSguJDD/t+xo29Z5TNsg3MQueZlKq+3MOfYNmyXRyQ8Eaj+JEUm02OjOC5clz58f3799ePvxyvk3Z4+/OnHYGABqlb7ZZ08CFWRDvPBoOHFasNnVcxVLFjhNDF7/1Nfzs17DZ8YYAL6OvawPVthDgO3uvRZ8w4nTau3s4giUYvL2ECvJT7fsgZ0Iz/aoB/mGTaB1tEvxZP//RDSZaDl3wgUuth+UY9g4rUJpj+JJLacxOzc+qkAqVY5h47T4kSv+98y0nMbs/MxnBXKOcgwbp0XlKn5zS1FOY7a5sBgeEhp5VqG1DP1roqaZ1n9FpkevDSU1n6B6nNbs88XGUyiVE7vOSsYEMjQfikyPq9o4rbmx0bA/uk5KwS5biRACNckJfhkZlm/YOC0S1W9WlIJq5Q6hu7KSZgwLGBhgbi18Iel8JJRv2DgtgmkNk9UhHA36IeTsbwfe8okBDHDgNPXgbmLnS6IFm+mRYe6QcJrMuAYKcT9O3b+TGJVKi3S06XcXTyEb4rEMM9EBDDAh7y+ddt1aDloigWxccHwdGN8O4RUwwITAT+GJ1k0rMe8aYZmWR8CsVlbLo4AHm2srq+VRwIPNtbUB1PoLAAD///W5JH0AAAAGSURBVAMAyfBQJI5bALcAAAAASUVORK5CYII=?
  2. Save & Exit the guide. Once saved, the image will be automatically uploaded and hosted on the OGL server, and the Base64 URL will be converted to a hosted URL.

Step 2: Generate Hosted URLs

  1. Re-open the guide in the Full Editor and double-click the image to open the Image Properties dialog.


    Properties1

    Notice that the OGL Editor has automatically changed the Base64 URL to an new hosted image URL like this:

    "https://guidedlearning.oracle.com/api/edge/app/EWxJBmADQGuGbk5T3yqnxQ/upload_content_image/601bry4/image/content_image"

    Note:

    The default image URL generated by the OGL Editor contains the file path: "https://guidedlearning.oracle.com/api/edge/app/...", which is is not publicly accessible for end-users in the host application and should NOT be used outside of the editor. You will need to update this URL to one that is publicly accessible by changing the file path to: "https://guidedlearning.oracle.com/player/latest/api/app/...". If you do not update these image URLs, these custom images will not display for host application end-users.
  2. Copy the entire new image URL from the URL field. Then paste it into a text editor, such as Notepad.
  3. In your text editor, replace the file path:

    /api/edge/app/... with /player/latest/api/app/...

    For example, if the original URL was:

    "https://guidedlearning.oracle.com/api/edge/app/EWxJBmADQGuGbk5T3yqnxQ/upload_content_image/601bry4/image/content_image"

    The new URL should be changed to:

    "https://guidedlearning.oracle.com/player/latest/api/app/EWxJBmADQGuGbk5T3yqnxQ/upload_content_image/601bry4/image/content_image"

  4. Repeat this process for all custom images that you wish to add to your OGL Design Kit, replacing all Base64 URLs with hosted image URLs, and ensuring that the file path for each image is updated to "/player/latest/api/app/".

    Note:

    It is recommended that you save these URLs in a text file for later use.

Step 3: Replace Base64 References
  1. Open your Theme Editor in OGL console.
  2. Locate the theme that you wish to update and export it, if needed.
  3. Open the Theme HTML file in a text editor, such as Notepad.
  4. Locate the Base64 URL strings (e.g., data:image/png;base64,...).
  5. Replace them with the hosted URL containing the updated file path: "/player/latest/api/app/".
  6. Repeat this process for all other images, replacing all Base64 URLs with the new hosted URLs throughout the theme to update all images.
  7. Save the Theme HTML file.
  8. In OGL, open the Theme Editor and upload the updated theme.

    Example:

    • ❌ Base64: data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...
    • ✅ Hosted URL: https://guidedlearning.oracle.com/api/edge/app/HSyW_l+GQEegD_2GtaL8bA/upload_content_image/05tthio/image/content_image

Step 4: Verify in Development
  1. Save changes to your theme and preview the theme in the OGL editor.
  2. Set the theme as DEV Theme


    Dev Theme

  3. Confirm images load correctly.

Step 5: Publish to Production
  1. Once all images have been verified, publish the updated theme from Development → Production.


    Prod Theme

  2. Ensure all custom images are restored without Base64 issues.

Temporary Workaround

  • Use the Default Theme (no Base64 URLs), if immediate stability is required.
  • Limitation: Custom images will be missing.
  • To restore visuals, follow the above steps to replace Base64 URLs with hosted URLs, and ensure that the file path of the URL is updated to "/player/latest/api/app/"

Best Practices

  • Never embed images as Base64 URLs.
  • Always use hosted URLs for images/icons, , and ensure that the file path of the URL is updated to "/player/latest/api/app/"
  • Document and share these practices internally and with customers.

Reference

For detailed framework instructions, see the official OGL User Guide.