Oplix Subsystem Reference - Help Center | Oplix

Oplix Subsystem Reference

This document provides an overview of the Oplix Subsystem, a core component of the Oplix plugin for Unreal Engine. It’s designed to help you understand its purpose, key features, and how it integrates with your game to provide feedback functionality.

⚠️ Framework Implementation

The Oplix Subsystem has been designed primarily as a starting framework and reference implementation for developers looking to integrate Oplix within Unreal Engine projects. It is intended to serve as an initial guideline.

We highly recommend that developers:

  • Review and modify the source code to align with their project-specific coding standards
  • Adapt naming conventions to match your project
  • Adjust architectural patterns as needed for your game

Overview

The Oplix Subsystem (UOplixSubsystem) acts as the central nervous system for all Oplix-related operations within your Unreal Engine project. Its primary goal is to handle the communication between your game client and the Oplix backend API.

Core Responsibilities

  1. Authenticating with the Oplix service to ensure secure communication
  2. Fetching dynamically configured feedback form templates from the Oplix platform
  3. Displaying these forms to the player using Unreal Engine’s UMG system with Common UI
  4. Collecting player feedback, along with relevant contextual information (screenshots, game state, device details)
  5. Submitting collected data securely back to the Oplix backend for analysis

It’s implemented as a UGameInstanceSubsystem, meaning it lives alongside your game instance and persists across level changes, ensuring continuous operation.

Core Functionality

💡 Authentication Management

Before any data can be exchanged, the plugin needs to authenticate with the Oplix API.

Authentication Process

On initialization (Initialize), the subsystem automatically starts the authentication flow using the App Key and Client Secret you provide in Project Settings > Plugins > Oplix (UOplixSettings).

Token Management

  • Access Token - Used for making API calls (limited lifespan tracked by TokenExpiryTime)
  • Refresh Token - Used for obtaining new access tokens without re-entering credentials

Automatic Refresh

The subsystem automatically detects when the AccessToken is about to expire (IsAccessTokenValid) and uses the RefreshToken to get a new one (RefreshAuthToken). This happens transparently without interrupting the user.

Resilience & Retry Logic

If authentication or token refresh fails (e.g., due to network issues), the subsystem implements a robust retry mechanism:

  • Uses exponential backoff (CalculateRetryDelay) to avoid overwhelming the server
  • Increases delay between retries up to a maximum limit
  • Temporarily disables authentication (EOplixAuthState::Disabled) after too many consecutive failures

State Tracking

Authentication status is tracked using the EOplixAuthState enum:

  • Idle - Initial state
  • Authenticating - Currently authenticating
  • Authenticated - Successfully authenticated
  • Failed - Authentication failed
  • Disabled - Too many failures, temporarily disabled
💡 Dynamic Form Loading

Instead of hardcoding feedback forms, Oplix allows you to configure them on the Oplix web platform.

Fetching Templates

Once authenticated, the subsystem calls GetAppTemplate to request the form structures associated with your App Key.

Data Structure

The response is parsed into the FOplixFormTemplatesInfo struct, which contains:

Form Template Structure

Field Name Type Required Notes
FOplixFormTemplatesInfo Struct Required Root container for all form templates
FOplixFormTemplateModel Struct Required Defines a specific form (description, type, layout)
FOplixFormDataModel Struct Required Contains rows of form fields
FOplixRowModel Struct Required Defines a row containing columns
FOplixColumnModel Struct Required Specifies questions, input types, required status, exclude flag

Input Types Supported

Each column can specify different input types via inputType, ratingScale, options, and labels:

  • Text input
  • Rating scales
  • Dropdowns
  • Checkboxes
  • Toggle switches

UI Population

Template data is used to dynamically construct the UI elements within the feedback window.

💡 UI Management (UOplixWindow)

The subsystem manages the main feedback user interface.

Window Creation

When ToggleOplixWindow is called (typically via UOplixBlueprintFunctionLibrary::ToggleOplixForm), the subsystem creates an instance of the UMG widget class specified in Oplix Settings (UOplixSettings->OplixWindowClass).

💡 Widget Requirements

The widget class must be a subclass of UOplixWindow.

Integration

The created UOplixWindow is given:

  • Reference to the UOplixSubsystem
  • Fetched OplixFormTemplatesInfo data during its SetupWindow phase

Display

The window is added to the player’s viewport and activated.

Toggling Behavior

Calling ToggleOplixWindow again will typically close the window if it’s already open (behavior depends on the specific UOplixWindow implementation).

💡 Data Collection & Submission

This is the core feedback loop where player input and context are gathered and sent.

User Input Collection

The UOplixWindow and its child widgets (like UOplixFormWidget) collect the user’s answers to the form questions.

Contextual Data

When the user submits the form, SubmitFormData automatically gathers:

Game/Session Info (FOplixFeedbackRequestSenderGameInfo):

  • Session duration
  • Current map (active_scene)
  • Quality settings
  • Resolution
  • Language
  • Engine version

Device Info (FOplixFeedbackRequestSenderDevice):

  • Operating system
  • CPU details
  • GPU details
  • RAM amount
  • Battery status
  • Device model
  • Orientation

Screenshot:

  • Captured from current viewport
  • Resized to max 1920x1080
  • Compressed into JPEG format

File Attachments (Optional):

  • Support for arbitrary files (log files, crash dumps, etc.)
  • Automatic MIME type detection (GetMimeTypeForFile)

Submission Format

All data is packaged into a multipart/form-data HTTP request containing:

  • Form answers (JSON)
  • Metadata (JSON)
  • Screenshot (binary)
  • Attached files (binary)

API Call

Request is sent to the Oplix backend’s v2/submitform endpoint using the current AccessToken for authorization.

Result Handling

The submission result (success or failure) is passed back to the UOplixWindow via:

OnSubmitRequestFinished -> FormWindow->SubmitResultReceived

This allows the UI to update accordingly (e.g., show success message or error).

Key Components & Classes

Core Subsystem Components

Field Name Type Required Notes
UOplixSubsystem UGameInstanceSubsystem Required Central coordinator for all Oplix operations. Handles authentication, API communication, UI window management, token refresh, and retry logic. Lives for the duration of the game instance.
UOplixSettings Configuration Asset Required Found in Project Settings > Plugins > Oplix. Contains AppKey, ClientSecret, UOplixWindowClass, bCreateDebugFiles, and window styling options.
UOplixWindow Base UMG Widget Required Main feedback window using Common UI. Displays tabs for multiple templates, hosts UOplixFormWidget, shows branding/logo, and communicates with subsystem for submission.
UOplixFormWidget UMG Widget Required Renders one specific form based on FOplixFormTemplateModel. Dynamically creates UOplixRowWidget instances, tracks answers (QuestionAnswerMap), validates required fields (RequiredQuestionsMap).
UOplixRowWidget UMG Widget Required Layouts questions (FOplixColumnModel) within a single row. Contains actual input elements (text boxes, dropdowns, rating scales, etc.).
UOplixBlueprintFunctionLibrary Blueprint Library Optional Provides Blueprint nodes for easy interaction. Primary function: ToggleOplixForm to show/hide feedback window.

Data Structure Types (C++ Headers)

Field Name Type Required Notes
FOplixRequestsTypes.h API Request/Response Required Defines structures that map to JSON data exchanged with Oplix API: FOplixAuthTokenRequest, FOplixTokenResponse, FGetFormTemplateRequestContent, FOplixFormTemplatesInfo, FOplixFeedbackRequestModel, FOplixFormField
OplixGenericTypes.h Form Layout/Styling Required Defines form layout and styling structures: FOplixFormTemplateModel (form definition), FOplixRowModel (row layout), FOplixColumnModel (field definition), FOplixOptionModel (dropdown options), FOplixWindowStyle (UI styling)

How It Works

💡 Understanding the Flow

The Oplix Subsystem orchestrates a complete lifecycle from game startup through form submission. Here’s how everything works together:

Game Startup & Authentication

When your game starts, UOplixSubsystem::Initialize is called automatically. The subsystem immediately attempts to authenticate with the Oplix API using the App Key and Client Secret from your UOplixSettings.

If authentication fails (network issues, invalid credentials, etc.), the subsystem implements exponential backoff retry logic - waiting progressively longer between attempts to avoid overwhelming the server. After too many failures, authentication is temporarily disabled.

Automatic Token Management

Once authenticated, you never need to worry about tokens again. The subsystem automatically refreshes the access token before it expires (every 15 minutes) using the refresh token. This happens transparently in the background.

Form Template Loading

Upon successful authentication, GetAppTemplate is called to fetch your form templates from the Oplix backend. These templates define:

  • What questions to ask players
  • Input types (text, rating, dropdown, etc.)
  • Required fields
  • Field exclusions (for sensitive data)
  • UI layout and styling

The response is parsed into structured data (FOplixFormTemplatesInfo) that’s used to dynamically build the UI.

Player Interaction Flow

When a player wants to submit feedback, they trigger the form (typically via a button or hotkey that calls ToggleOplixForm from the Blueprint library).

The UOplixSubsystem creates an instance of your configured UOplixWindow widget and passes it:

  • A reference to itself (for callbacks)
  • The fetched form template data

The window is added to the viewport and activated. If you have multiple form templates, tabs are displayed for the player to choose which type of feedback they’re submitting.

Data Collection & Submission

As the player fills out the form, UOplixFormWidget tracks their answers in real-time and validates required fields. When they click submit, here’s what happens:

💡 Step 1: Gather Form Answers

The widget collects all question/response pairs, including the exclude flag for each field (used to mark sensitive data that shouldn’t be processed by AI).

💡 Step 2: Capture Screenshot

The subsystem automatically captures the current viewport, resizes it to a maximum of 1920x1080, and compresses it to JPEG format to keep file sizes manageable.

💡 Step 3: Collect Contextual Data

Two critical data structures are populated automatically:

Game/Session Info - Session duration, current map name, quality settings, resolution, selected language, engine version, and custom game state data.

Device Info - Operating system, CPU model, GPU details, RAM amount, battery status (for mobile), device model, and orientation.

This contextual data is invaluable for reproducing and debugging issues.

💡 Step 4: Attach Optional Files

If you’ve provided file paths (like log files or crash dumps), the subsystem reads them and determines the appropriate MIME type for each.

💡 Step 5: Package & Send

All collected data is packaged into a multipart/form-data HTTP request containing:

  • Form answers (JSON)
  • Device metadata (JSON)
  • Game metadata (JSON)
  • Screenshot (binary)
  • Additional files (binary)

The request is sent to /v2/submitform with the current AccessToken. If the token is about to expire, it’s automatically refreshed first.

💡 Step 6: Handle Response

The submission result is passed back to the UI via OnSubmitRequestFinished -> FormWindow->SubmitResultReceived. Your window can then:

  • Show a success message
  • Display error details if submission failed
  • Close the window or allow another submission

Getting Started

✨ Quick Setup

Follow these steps to integrate the Oplix Subsystem into your Unreal Engine project.

Ensure the Oplix Plugin is enabled in your project via Edit > Plugins.

Navigate to Project Settings > Plugins > Oplix and enter:

  • Your unique App Key
  • Your Client Secret (from Oplix dashboard)

Ensure a valid Oplix Window Class (derived from UOplixWindow) is assigned. You can use the default provided with the plugin or create your own customized version.

In your game’s UI or input handling logic, call the Toggle Oplix Form Blueprint node when you want the player to be able to open the feedback window.

[Event BeginPlay (or Button Click Event)] ---> [Toggle Oplix Form]
You're Ready!

Your Oplix integration is now complete. Players can submit feedback directly from your game!