Request Form API

Overview

The v2/requestform endpoint allows game studios to retrieve in-game form templates created in the Oplix Dashboard using secure token-based authentication. These templates are used to collect feedback, bug reports, or other information from users during gameplay.

Note - This endpoint introduces a token exchange, please read the implementation plan below

URL:

• Base Endpoint: https://backend.oplix.io/api/engine
• Endpoint: POST /v2/requestform
• HTTP Method: POST
• Content-Type: application/json

This endpoint retrieves form templates associated with your application ID (appId). It requires a valid access token obtained through the Oplix token authentication flow.

Headers:

Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

• Content-Type: Must be application/json.
• Authorization: Must contain a valid Oplix access token prefixed with Bearer .

Request Structure

The request should include a JSON body containing the appId to identify which application’s form templates should be retrieved.

In-Game Authentication Flow

Here’s a clear flow you should follow to securely call the POST /v2/requestform endpoint:

1. Obtain Tokens (First Time Auth)

To retrieve your first Access Token and Refresh Token, call:

Endpoint: POST /auth/token

Request Body:

{
  "appId": "YOUR_APP_ID",
  "clientSecret": "YOUR_CLIENT_SECRET"
}

Response Example:

{
  "accessToken": "ACCESS_TOKEN",
  "refreshToken": "REFRESH_TOKEN",
  "expiresIn": 900 // in seconds (15 minutes)
}

Important: Your client secret is a sensitive credential gained in the Team Settings page on the Oplix Dashboard. It must be kept secure and never exposed to end users. Each client secret is tied to your team account and can be revoked independently from your app ID if compromised.

2. Check Access Token Validity

Before calling /v2/requestform, ensure your Access Token is still valid:

• Access Token expires in: 15 minutes
• You can check expiry using the expiresIn field or by storing the expiry timestamp.

3. Refresh Token (When Access Token Expired)

If your Access Token has expired, use your stored Refresh Token to obtain a new one.

Endpoint: POST /auth/refresh

Request Body:

{
  "refreshToken": "YOUR_REFRESH_TOKEN"
}

Response Example:

{
  "accessToken": "NEW_ACCESS_TOKEN",
  "refreshToken": "NEW_REFRESH_TOKEN", // May be the same or rotated
  "expiresIn": 900
}

Note: If the Refresh Token has expired (after 7 days) or is invalid, you must go back to Step 1 and re-authenticate. It would be beneficial to reauthenticate new tokens on game initialisation

4. Make the API Call to Retrieve Form Templates

Once you have a valid Access Token, make a POST request to /v2/requestform.

HTTP Request:

POST /v2/requestform
Host: backend.oplix.io
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Request Body:

{
  "appId": "YOUR_APP_ID"
}

Token Expiry Summary

• Access token expiration: 15 minutes
• Refresh token expiration: 7 days

Response Structure

The response will be in JSON format. On success, it returns an array of form templates associated with the specified appId. On failure, it returns an error message.

Success Response (200 OK):

The response includes a templates array. Each template object contains metadata like formDescription and templateType, along with an array of rows. Each row contains columns, where each column defines an input field (its inputType, question, options, required status, layout width, and the exclude flag).

{
  "templates": [
    {
      "formDescription": "General Bug Report",
      "templateType": "Bug Report",
      "rows": [
        {
          "id": 1713449292001,
          "columns": [
            {
              "id": 1713449292002,
              "width": 50,
              "exclude": false, // Field included in automatic processing
              "question": "Which area of the game did you experience the issue in?",
              "required": false,
              "inputType": "dropdown",
              "options": {
                "type": "dropdown",
                "options": [
                  {"label": "Gameplay", "value": "Gameplay"},
                  {"label": "UI/UX", "value": "UI/UX"},
                  {"label": "Performance", "value": "Performance"},
                  {"label": "Audio", "value": "Audio"},
                  {"label": "Other", "value": "Other"}
                ]
              }
            },
            {
              "id": 1713449292003,
              "width": 50,
              "exclude": false,
              "question": "What were you doing when the issue occurred?",
              "required": false,
              "inputType": "text"
            }
          ]
        },
        {
          "id": 1713449292004,
          "columns": [
            {
              "id": 1713449292005,
              "width": 67,
              "exclude": false,
              "question": "How frequently does this issue occur?",
              "required": false,
              "inputType": "rating",
              "ratingScale": {
                "type": "custom",
                "labels": ["Once", "Occasionally", "Often", "Always"]
              }
            },
            {
                "id": 1725461943474,
                "width": 33,
                "exclude": false,
                "question": "Did this issue cause the game to crash?",
                "inputType": "switch",
                "labels": {
                  "type": "toggle",
                  "options": {
                    "on": "Yes",
                    "off": "No"
                  }
                }
              }
           ]
        },
        {
          "id": 1713449292007,
          "columns": [
            {
              "id": 1713449292008,
              "width": 100,
              "exclude": false,
              "question": "Please provide a detailed description of the issue:",
              "required": false,
              "inputType": "paragraph"
            }
          ]
        },
        {
          "id": 1713449292009,
          "columns": [
            {
              "id": 1713449292010,
              "width": 67,
              "exclude": false,
              "question": "Rate the severity of the issue",
              "required": false,
              "inputType": "rating",
              "ratingScale": {
                "type": "custom",
                "labels": ["1 (low)", "2", "3", "4", "5 (high)"]
              }
            },
            {
              "id": 1727261763106,
              "width": 33,
              "exclude": true, // Field excluded from automatic processing
              "question": "Your email",
              "required": false,
              "inputType": "text"
            }
          ]
        }
      ]
    }
    // ... potentially more templates
  ]
}

Explanation of the exclude Flag:

• exclude: true: This flag indicates that the field should be excluded from automatic processing by the Oplix AI engine. The data will still be collected and stored with the submission for manual review.
• exclude: false: This flag indicates that the field will be processed normally by the Oplix backend systems as part of the form submission analysis.

Error Responses

Error Response (Unauthorized):

This can occur due to several reasons related to authentication:

• Missing Authorization header.
• Invalid token format (e.g., not starting with Bearer ).
• Token signature verification failed.
• Access token has expired (requires refresh).
• Token has been revoked.
• Incorrect token type used.
• The appId provided in the body does not exist or does not match the application associated with the token.

{
  "error": "Token expired",
  "code": "TOKEN_EXPIRED"
}

{
  "error": "Invalid token",
  "code": "INVALID_TOKEN"
}

{
  "error": "App ID 2fad4375-5199-4ca1-9714-0048e15047c7 does not exist"
}

Error Response (404 Not Found):

This occurs if the specified appId is valid but has no form templates associated with it in the Oplix Dashboard.

Action: Go to Setup -> Game Engine -> Applications in the Oplix Dashboard to ensure templates have been added to the application corresponding to the appId.

{
    "error": "No templates are associated with App ID 2fad4375-5199-4ca1-9714-0028e15047c9"
}

Error Response (429 Too Many Requests):

This occurs if the API rate limit for your application has been exceeded.

{
    "error": "Too many requests",
    "retryAfter": 58, // Seconds to wait before retrying
    "message": "Rate limit exceeded. Please try again in 58 seconds."
}

Additional Information**:**

• CORS Support: The API includes CORS headers to allow cross-origin requests from web-based game clients.
• App ID Validation: Ensure that the appId is valid and corresponds to a registered application. Submissions with invalid or missing appId will result in an error.
• Secret Keys: Revoked client secrets immediately invalidate all associated tokens. Each secret key is uniquely tied to your team within Oplix and can be used with any of your team’s apps