DETECT WEB ENTITIES =======================

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

📋 ELEMENT DESCRIPTION
--------------------------------
GOOGLE VISION - WEB ENTITIES (FRONT-END DESKTOP & NATIVE MOBILE) provides client-side processing for web entity detection, ideal for applications requiring immediate responsiveness.

🔧 STEP-BY-STEP SETUP
--------------------------------
ℹ️ The steps from 0) to 1) can be automatically performed using the automated configuration script mentioned above.

0) Set up a project in Google Cloud Console (as described in Back-End setup)

1) Copy credentials to Plugin settings (as described in Back-End setup)

2) Register on plugins.wiseable.io and create a new Credential associating your BUBBLE APP URL, GCP PROJECT_ID, CLIENT_EMAIL & PRIVATE_KEY
The service will generate your PUBLIC ACCESS KEY - a secure proxy for your API key tied to your domain for security

3) Enter your PUBLIC ACCESS KEY in the PLUGIN SETTINGS

4) Add the GOOGLE VISION - WEB ENTITIES (FRONT-END DESKTOP & NATIVE MOBILE) element to your page

5) Configure the element:

FIELDS:
- RESULT DATA TYPE: Must always be set to "RESULT (VISION - WEB ENTITIES)"

EVENTS:
- SUCCESS: Triggered upon successful detection
- ERROR: Triggered when an error occurs - ALWAYS implement this event

EXPOSED STATES:
- RESULTS: Populated upon SUCCESS - contains web entity detection results
- ERROR MESSAGE: Populated upon ERROR - contains detailed error information
- IS PROCESSING: True when processing is in progress

ELEMENT ACTIONS:
- DETECT WEB ENTITIES (FRONT-END & NATIVE MOBILE): Trigger web entity detection from image

ACTION INPUT FIELDS:
- IMAGE: Image from Bubble uploader, Protocol-relative URLs (//server/file.ext), HTTPS URLs (https://server/file.ext), or Google Storage URIs (gs://bucket/image.jpg)
- MAX RESULTS: Maximum entities to return (Default: 5)

2️⃣: DETECT WEB ENTITIES (BACK-END)
==================================

📋 ACTION DESCRIPTION
--------------------------------
DETECT WEB ENTITIES from an image file returns a list of web entities. For each entity, it returns the web URL, textual description, confidence score, entity code, and best guess label.

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

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 in Google Cloud Console: https://cloud.google.com/vision/docs/common/auth#enabling_the_api
- 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 and copy/paste these parameters to Plugin settings:
- CLIENT_EMAIL
- PROJECT_ID
- PRIVATE_KEY (include -----BEGIN PRIVATE KEY-----\n prefix and \n-----END PRIVATE KEY-----\n suffix)

2) Set up the "DETECT WEB ENTITIES (BACK-END)" action in your workflow:

INPUT FIELDS:
- IMAGE: JPEG, PNG8, PNG24, GIF, Animated GIF (first frame only), BMP, WEBP, RAW, ICO, PDF, TIFF image file from Bubble's picture uploader, Protocol-relative URLs (//server/image.jpg), HTTPS image URL (https://server/image.jpg), or Google Storage URL (gs://bucket/image.jpg)
- MAX RESULTS: Maximum number of entities returned (Default: 5)
- OUTPUT TYPE: Must always be set to "RESULT (VISION)"

OUTPUT FIELDS:
- RESULT: Returns a list of web entities with URLs, descriptions, confidence scores, entity codes, and best guess labels


🔍 IMPLEMENTATION EXAMPLE
======================
Browse the demo app editor for complete implementation examples.

ℹ️ ADDITIONAL INFORMATION
======================
> Supported image formats: https://cloud.google.com/vision/docs/supported-files
> Google Vision service limits: https://cloud.google.com/vision/quotas

⚠️ TROUBLESHOOTING
================
BACK-END ACTIONS:
Check the Logs tab → "Server logs" in your App Editor
Ensure "Plugin server side output" and "Plugin server side output" are selected in "Show Advanced"

FRONT-END ACTIONS:
Open browser developer console (F12 or Ctrl+Shift+I) for detailed error messages
Always check the ERROR MESSAGE state and implement ERROR event handling

IMPORTANT: The ERROR EVENT and ERROR MESSAGE STATE are critical for proper error handling and user experience

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

GENERAL
-------------
For back-end actions, this implementation posts the file data to Google Vision for non-Google Storage URLs (e.g: non-gs://). The maximum processing duration of this action is capped at 30 seconds as per Bubble.io design. This time limitation does not apply to front-end actions.

⏱️ 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.

FRONT-END VS BACK-END PROCESSING
----------------------------------------------------
The front-end element is designed to support and optimize multiple image formats and will automatically compress images to adhere to Google Cloud Vision API 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 additional features or support questions.