Opineos logo Opineos
Start Now
Production Documentation

Opineos Documentation

This documentation reflects the current backend behavior in this repository. Opineos is project-first: each project has its own domain, widget config, embed script URL and feedback stream.

This page is aligned with the current backend implementation. It covers setup, runtime behavior, API payloads, integrations, and production troubleshooting in one place.

Layer 1
Create Project

Defines workspace scope, domain guard, and widget config source.

Layer 2
Configure Widget

Visual tokens, launcher behavior, text content, help links.

Layer 3
Install Script

Script delivery is origin validated and generated from live config.

Layer 4
Process Feedback

Review, classify, change status, dispatch to external systems.

When to use this page

  • New workspace setup and first deployment.
  • Widget design/token customization and QA.
  • Origin/domain mismatch debugging.
  • API integration and webhook validation.

Quick Start (End-to-End)

  1. Create a project in Projects.
  2. Set domain_address as a full origin:
    https://app.example.com or wildcard https://*.example.com.
  3. Open project detail page and configure widget settings.
  4. Copy embed script URL from install box in project detail.
  5. Add script before </body> on target pages.
  6. Submit test feedback and verify in dashboard + integrations.
<script src="https://YOUR-OPINEOS-HOST/script/{base64-origin}.js"></script>

Project and Domain Model

Exact Origin Projects

  • Use for a single app host.
  • Example: https://erp.example.com.
  • Strict scheme + host (+ port when present).

Wildcard Origin Projects

  • Use for subdomain families.
  • Example: https://*.webofis.im.
  • Matches subdomains (not root domain).
For wildcard setup, keep one shared widget configuration and separate tenants using metadata (for example hostname) in downstream analysis.

Widget Settings Guide

General Tab

  • Launcher position (4 corners).
  • Launcher icon class (Font Awesome).
  • Full text content controls for both views.

Colors + Help Tab

  • Theme mode: light/dark/auto.
  • Token-based color system (header/panel/card/input/rating/help icon).
  • Help menu links: max 5 items.
  • Help icon class + icon colors.

Dashboard-Editable Areas (Current)

  • Launcher size/position/icon and mobile sizing behavior.
  • Header/panel/card/input/rating/help-icon color tokens.
  • Help item icon class and icon background/text colors.
  • Help menu links and form texts.
  • Preview parity for Landing and Dashboard previews.

For deep token reference and practical examples, see Widget Customization.

Installation and Script Runtime

Script Endpoint

GET /script/{hash}.js
  • Returns generated JS+CSS from current config.
  • Response type: application/javascript.
  • No-store cache headers are sent to prevent stale runtime.

Runtime Behavior

  • Widget opens as floating panel + launcher button.
  • Theme variables are injected from project config.
  • Feedback form supports optional screenshot upload/auto-capture.

Go-Live Checklist

Use this checklist before shipping widget changes to production.

Functional Checks

  • Launcher opens/closes smoothly on desktop and mobile.
  • Home screen cards have hover elevation animation (desktop).
  • Feedback validation shows field-specific errors (email/message).
  • Feedback submit success appears in dashboard list.
  • Integration test events are delivered.

Visual Checks

  • No host-site CSS overrides on title, text, or inputs.
  • Input fields keep fixed height, padding, borders, and radius.
  • Help action icons are visible and centered in all cards.
  • Mobile launcher size and icon size match configured values.
  • Preview and runtime script look identical.

Feedback Lifecycle

1. Collect

Visitor submits rating, message, category, and optional email/screenshot.

2. Store

Backend validates request and stores feedback + metadata. Validation errors are returned by field (email/message) for clarity.

3. Dispatch

Enabled integrations receive created/status events.

4. Process

Team reviews in dashboard, updates status, adds notes.

Integrations and Events

Provider configs are stored per user connection and dispatched after save/status changes.

Supported Providers

  • Webhook
  • GitLab issue
  • Git issue (GitHub compatible API)
  • Slack incoming webhook
  • Telegram bot

Trigger Behavior

  • feedback.created dispatched after successful save.
  • feedback.status_updated dispatched on status changes.
  • integration.test available via integration test actions.
  • Integration test is marked success only on successful HTTP response.

Public API Guide

Primary public write endpoint:

POST /api/feedback/{hash}

Required

  • rate (1..5)
  • feedback (min 8 chars)

Optional

  • email, type
  • screenshot_upload / screenshot_auto
  • metadata or metadata_json

See the full technical contract and examples in API Reference.

Security

  • Widget script does not include integration credentials.
  • Origin/hash validation is enforced server-side before feedback save.
  • Domain supports exact and wildcard host matching based on project configuration.
  • Inactive projects do not serve script and do not accept submissions.
  • Empty secret/token updates keep previous value in integrations form.
  • Runtime styles are namespaced and hardened to reduce host CSS override impact.

Limits and Current Behavior

  • Help menu supports maximum 5 links per project.
  • Screenshot upload supports jpg/jpeg/png/webp, max 5MB.
  • Public write endpoint is currently POST /api/feedback/{hash}.
  • Integration dispatch failures are logged; request flow continues.
  • Wildcard domain pattern is designed for subdomain families, not arbitrary host matching.

Troubleshooting Playbook

Widget script returns 404

  • Hash does not map to configured project domain.
  • Request origin/referer does not match expected origin/wildcard rule.
  • Project is inactive.

Feedback submit validation fails

  • Message must be at least 8 characters.
  • Email must be valid if provided.
  • Screenshot file must match allowed types and max size.

Integration test fails

  • Provider may be disabled or missing required config.
  • Target endpoint may be unreachable from server.
  • Credentials/token might be invalid for external API.

Widget looks broken on host site

  • Check host global CSS reset/form-control conflicts.
  • Hard refresh page and re-test after config updates.
  • Verify icon classes and Font Awesome availability.

Icons are missing or appear as empty squares

  • Confirm icon class value is valid for installed Font Awesome version.
  • Check that font-family for icon element is not overridden by host CSS.
  • Verify icon color is not same as icon background token.