1️⃣: GOOGLE VISION - OCR DOCUMENT (FRONT-END DESKTOP & NATIVE MOBILE) ==================================================================

📋 ELEMENT DESCRIPTION
--------------------------------
GOOGLE VISION - OCR DOCUMENT (FRONT-END DESKTOP & NATIVE MOBILE) provides PERFORM OCR ON FILE action to extract text within a PDF, TIFF or GIF file provided as input, using Google Vision's powerful AI. The front-end element is suitable for applications when reactivity is desired, such as but not limited to, mobile applications. It supports multiple image formats and automatically optimizes documents to meet Google Cloud requirements.

🔧 STEP-BY-STEP SETUP
--------------------------------
ℹ️ The steps from 0) to 1) can be automatically performed by logging in into your Google Cloud Console, opening the Cloud Shell (top right corner of your page) and copy pasting this command and press enter:

 wget -q https://storage.googleapis.com/bubblegcpdemo/demo-assets/wiseable-gcp-vision.py && python3 wiseable-gcp-vision.py

Otherwise, follow these manual steps:

0) Set-up a project from Google Cloud Console: https://cloud.google.com/vision/docs/setup
 - Create or select a project
 - Enable the CLOUD VISION API for that project
 - Create a service account
 - Download a private key as JSON.

1) Open the private key JSON file with a text editor, copy/paste the following parameters from your file to the Plugin settings:
 - CLIENT_EMAIL
 - PROJECT_ID
 - PRIVATE_KEY, including the -----BEGIN PRIVATE KEY-----\\n prefix and \\n-----END PRIVATE KEY-----\\n suffix.

2) Register on plugins.wiseable.io. Create a new Credential which associates your BUBBLE APP URL, GOOGLE CLOUD credentials.
The registration service will generate your PUBLIC ACCESS KEY. This key serves as a secure proxy for your real API key. It allows your application to communicate with the service without exposing your real API key. Since this PUBLIC ACCESS KEY is explicitly tied to your registered BUBBLE APP URL, it can only be used from that domain, ensuring that even if the key is publicly visible, it remains safe and cannot be misused by unauthorized sources.

3) Enter in the PLUGIN SETTINGS your PUBLIC ACCESS KEY (used for the front-end element only).

4) Add the GOOGLE VISION - OCR DOCUMENT (FRONT-END DESKTOP & NATIVE MOBILE) element to the page on which the OCR feature must be integrated. Select the RESULT DATA TYPE as Returned type, must always be set to "RESULT (VISION - OCR DOCUMENT)".

5) Integrate the logic into your application using the following GOOGLE VISION - OCR DOCUMENT (FRONT-END DESKTOP & NATIVE MOBILE) element's states and actions:

FIELDS:
- RESULT DATA TYPE: Returned type, must always be set to "RESULT (VISION - OCR DOCUMENT)".  

EVENTS:
- SUCCESS: Event triggered upon success
- ERROR: Event triggered upon error

EXPOSED STATES:
Use any element able to show/process the data of interest (such as a Group with a Text field) stored within the result of the following states of the GOOGLE VISION - OCR DOCUMENT (FRONT-END DESKTOP & NATIVE MOBILE) element:
- RESULTS: Populated upon SUCCESS event. Returns a list of pages along with their full text annotations, dimensions, and confidence score.
- ERROR MESSAGE: Populated upon ERROR event.
- IS PROCESSING: Set to true when processing is in progress, false otherwise.

ELEMENT ACTIONS - TRIGGERED IN WORKFLOW:
- PERFORM OCR ON FILE (FRONT-END DESKTOP & NATIVE MOBILE): Extract text from a document. Populate RESULTS state upon completion.

  Inputs Fields:
     - FILE: PDF, TIFF or GIF file from the Bubble.io picture uploader, a Protocol-relative URLs (//server/file.ext), or a HTTPS file URL (https://server/file.ext) or a Google Storage URL (gs://bucket/file.ext).

2️⃣: PERFORM OCR ON FILE (BACK-END)
==================================

📋 ACTION DESCRIPTION
--------------------------------
PERFORM OCR ON FILE extracts text within a PDF, TIFF or GIF file provided as input, using Google Vision's powerful AI.
The back-end action is suitable for applications when volume or asynchronous processing is desired.

🔧 STEP-BY-STEP SETUP
--------------------------------
ℹ️ If not already done, perform steps 0 and 1 of the first element setup. The back-end action does not require the PUBLIC ACCESS KEY.

1) Set up the action "PERFORM OCR ON FILE (BACK-END)" action in the workflow.

  Input Fields:
     - FILE: PDF, TIFF or GIF file from the Bubble.io picture uploader, a Protocol-relative URLs (//server/file.ext), or a HTTPS file URL (https://server/file.ext) or a Google Storage URL (gs://bucket/file.ext).
                 You can request online feature detection and annotation of 5 frames (GIF; "image/gif") or pages (PDF; "application/pdf", or TIFF; "image/tiff") of your choosing for each file.
     - MIME TYPE: Required for Google Storage URL (gs://bucket/file.ext) only, otherwise ignored. Valid values are: 'application/pdf', 'image/gif' or 'image/tiff'.
     - RESULT DATA TYPE: Returned type, must always be set to "RESULT (VISION - OCR DOCUMENT)".

  Output Fields:
     - RESULT: Returns a list of pages along with their full text annotations, dimensions, and confidence score.

🔍 IMPLEMENTATION EXAMPLE
======================
Feel free to browse the app editor in the Service URL for an implementation example.

ℹ️ ADDITIONAL INFORMATION
======================
> Supported file formats: PDF, TIFF or GIF for back-end actions. The front-end element supports additional formats and will automatically convert them to compatible formats.

> Supported languages: https://cloud.google.com/vision/docs/languages#supported-langs

> GOOGLE VISION service limits: https://cloud.google.com/vision/quotas

⚠️ TROUBLESHOOTING
================
Any plugin related error will be posted to the the Logs tab, "Server logs" section of your App Editor.
Make sure that "Plugin server side output" and "Plugin server side output" is selected in "Show Advanced".

For front-end actions, you can also open your browser's developer console (F12 or Ctrl+Shift+I in most browsers) to view detailed error messages and logs.

Always check the ERROR MESSAGE state of the element and implement error handling using the ERROR event to provide a better user experience.

> Server Logs Details: https://manual.bubble.io/core-resources/bubbles-interface/logs-tab#server-logs

⚡ PERFORMANCE CONSIDERATIONS
===========================

⏱️ BACK-END ACTION START DELAY
-----------------------------------------------
Each time a server-side action is called, Bubble initializes a small virtual machine to execute the action. If the same action is called shortly after, the caching mechanism kicks in, resulting in faster execution on subsequent calls.

A useful workaround is to fire a dummy execution at page load, which pre-warms the Bubble engine for the next few minutes, reducing the impact of cold starts for your users.

⏳ PROCESSING TIME LIMITS
-----------------------------------------------
For back-end actions, the maximum processing duration is capped at 30 seconds as per Bubble.io design. This time limitation does not apply to front-end actions.

FRONT-END VS BACK-END PROCESSING
----------------------------------------------------
The front-end element is designed to support and optimize multiple document formats and will automatically compress files to adhere to Google Cloud requirements. The back-end action doesn't perform this optimization, so be careful with file size and format when using it.

❓ QUESTIONS?
===========
Contact us at [email protected] for any additional feature you would require or support question.