📖 Full Instructions
1. Setup the Smart Element
Drag the OptiCache PRO Controller element onto your page (we recommend placing it inside a reusable header so it's everywhere). This element is invisible.

2. Saving Data (Set Smart Cache)
Use the element action Set Smart Cache.

Define a key_name (e.g., "dashboard_stats").

Provide the value_text (your text or stringified JSON).

PRO Tip: Set ttl_minutes to 60 so the data expires in an hour, and map user_id to Current User's Unique ID to keep the cache private!

3. Reading Data (Get Smart Cache)
Run the element action Get Smart Cache.

CRUCIAL: Because frontend actions are instant, you must use the element's event "OptiCache PRO Controller - Cache Loaded" to trigger the rest of your workflow.

Once that event fires, check Result of step's is_found to see if the cache is still valid. If yes, display the cached_value! If no (or if the TTL expired), run your standard Bubble DB Search.


How to setup your Global Server Cache:

Create a free account at Upstash (upstash.com) and navigate to the Redis section.

Click + Create Database, give it a name, and choose the region closest to your users.

Once created, scroll down to the REST API section to find your UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN.

How to Save Data to the Server:

In your backend or frontend workflow, select the Set Server Cache action.

Paste your Upstash REST URL and Token.

Define a cache_key (e.g., "pricing_tiers") and the cache_value (text or JSON).

(Optional) Set a ttl_seconds if you want the cache to auto-delete after a certain time (e.g., 3600 for 1 hour).

How to Retrieve Data from the Server:

Use the Get Server Cache action.

Provide your credentials and the cache_key you want to retrieve.

Use the returned cached_value in your next workflow steps!

How to Clear Server Cache:

When your main database updates (e.g., you changed a product price), use the Invalidate Server Cache action with the specific cache_key to instantly clear the old data globally.


📚 How to Setup the "Get Hybrid Cache" Workflow (L1 ➔ L2 ➔ L3)
The Get Hybrid Cache action is the crown jewel of Opticache Pro V3. It acts as an intelligent retriever that scans ultra-fast browser memory (L1/L2) and securely delegates to your backend (L3 - Redis) ONLY if the data is missing.

Because we prioritize strict Enterprise security, Client-Side actions should never hold your private API keys. Instead, we use the Delegation Pattern. Here is exactly how to set it up in your Bubble app:

Step 1: Trigger the Hybrid Cache Search
When a user loads a page or clicks a button, you need to tell Opticache to start searching for the data.

Create a Workflow (e.g., When Page is Loaded or When Button is clicked).

Add the action: Opticache - Get Hybrid Cache.

Fill in the fields:

Key Name: The specific data key (e.g., dashboard_stats).

Namespace: Group your cache (e.g., dashboard).

Version: Your app version (e.g., v1).

Enable SWR: Set to yes if you want instant stale-data loading (explained in Step 3).

Behind the scenes: The plugin will instantly check L1 (Session Storage) and L2 (Local Storage). If the data is there, it publishes the cached_value state instantly in 1ms!

Step 2: Set up the "L3 Fetch Required" Workflow (Secure Delegation)
If the data is NOT found in the browser (or if it's the user's first time visiting), the plugin will "raise its hand" and trigger a specific Bubble event to ask your secure backend for help.

Go to your Workflow tab and add a new event: Elements ➔ An Opticache - L3 Fetch Required.

Action 1 (Fetch Securely): Inside this workflow, run your Server-Side action: Opticache - Get Server Cache (Upstash). Fill in your secure REST URL, Token, and the exact same Key Name.

Action 2 (The Inverse Cascade): Now that your server has securely retrieved the data, we need to push it down to the user's browser so it loads in 1ms next time. Add the Client-Side action: Opticache - Set Smart Cache.

Key Name: The exact same key.

Value Text: Result of step 1's cached_value.

Storage Type: Local (The engine will automatically promote it to Session/L1 as well).

Step 3: Handle Background Revalidation (Stale-While-Revalidate)
If you set Enable SWR = yes in Step 1, the plugin will behave magically when a cache expires. Instead of showing an empty screen, it will immediately display the expired data to the user, and then ask the server for fresh data.

Add a new event: Elements ➔ An Opticache - Background Revalidation Required.

Build the exact same workflow as Step 2:

Run the Server-Side Get Server Cache.

Run the Client-Side Set Smart Cache to inject the fresh data.

(Optional UI Trick): You can show a tiny spinning ↻ icon somewhere on your screen while this workflow runs, and hide it when the Set Smart Cache action finishes. The user's screen will seamlessly update with fresh numbers without ever freezing!