Copresence Integration API

Copresence offers a method to integrate the avatar creation technology. This enables your users to use their likeness in your application or game.

Use Case

Before technical details, we present a common use case of interaction with integrated avatar technology from an end user’s perspective.

A video game running on a video game console offers face scanning during character creation. When a user decides to use this feature, the game presents them with a QR code. The Copresence app, or an app clip of it, if it’s not already installed, opens once the user scans the code with their phone.

The user can then record a new avatar using the Copresence app, or choose to use an already existing avatar if the app was already installed. The video game console can then download the exported avatar assets a single time using URLs provided by the Copresence API and allow the user to use their likeness for character creation. See the next subsections for details about linking to the Copresence app and obtaining asset URLs from the Copresence API.

Business Accounts and Export Tokens

Authentication with the Copresence backend works based on an account system. You as a customer can create an account on the Copresence platform. Your account will be assigned a business account role by the admins, indicating the account belongs to you, can be used for billing and to track metrics such as the number of avatars created through your services. Once a business account is set up, you can authenticate with the Copresence backend through an API request to receive a session token in response. A session token is a temporary string to be used as header in further API requests to the Copresence backend in order to unlock business account exclusive permissions.

Once authenticated as a business account, you can request the creation of Export Tokens through the Copresence Integration API. Export Tokens are unique temporary identifiers for a single avatar, which can be used to download the avatar’s exported assets once.

Expanding on the use case presented in the previous section, Export Tokens are used to streamline the connection between your software, end user avatars, and the Copresence backend through the following steps:

  1. Your backend requests the creation of an Export Token through the Copresence Integration API.

  2. Your backend transmits the Export Token to a device running one of your applications/clients.

  3. Device running application/client includes the Export Token as a query parameter inside a URL.

    3a. If the device running the application is a phone compatible with the Copresence app, the device accesses the URL directly and opens the Copresence app or an app clip of it.

    3b. If the device running the application is not a phone compatible with the Copresence app, it displays the URL as a QR code which opens the Copresence app or an app clip of it when scanned.

  4. The end user records a new avatar, or chooses to use an already existing one if the Copresence app was already installed.

  5. After recording or selection, the avatar is associated with the Export Token.

  6. The device running your application can get information about the avatar associated with the Export Token through a request to the Copresence Integration API.

    6a. The response either contains temporary URLs to the avatar’s files, or a status report if the avatar is not yet done processing.

    6b. Once the URLs to the avatar’s exported assets are successfully delivered, the Export Token is invalidated.

The following diagram is a visualisation of how the Copresence Integration API should be used to connect end users and your software with the avatar creation technology:

_images/export_token_workflow.png

API Endpoints

Below is a specification of API endpoints necessary to implement the Copresence Integration API as previously described:

POST /generateExportToken

Generate an Export Token

Generates an Export Token object in the Copresence backend, associates it with the requesting business customer account, and returns the token’s string as a response.

Status Codes:
Request Headers:

  • X-Copresence-REST-API-Key – REST API key for the Copresence API

  • X-Copresence-Session-Token – Session token received by authenticating as a business account.

Response JSON Object:

  • token (string) – Unique string identifier for an Export Token in the Copresence backend.

GET /redeemExportToken

Redeem an Export Token to get file URLs

Attempts to redeem an Export Token.

If the avatar associated with the Export Token has successfully completed, the response body contains one-time download URLs to all necessary avatar exports.

If the avatar associated with the Export Token is incomplete or the user has not associated any avatar with the token yet, the response will contain information regarding the status of the avatar.

A boolean flag inside the response indicates the status of the avatar.

Once the Copresence backend provides a response with download URLs, the provided Export Token is invalidated by the backend.

Status Codes:

  • 200 OK – Export token is still active, and its associated avatar exports are either still being processed or ready to download.

  • 400 Bad Request – Provided Export Token string does not match an active Export Token in the Copresence backend

  • 500 Internal Server Error – Internal server error

Request Headers:

  • X-Copresence-REST-API-Key – REST API key for the Copresence API

  • X-Copresence-Export-Token – String of an Export Token generated by the /generateExportToken endpoint

Response JSON Object:

  • avatar_ready (boolean) – True if the avatar associated with the provided Export Token has been completely processed, indicating the ‘payload_complete’ property is present in the response and contains download URLs. False if the avatar associated with the provided Export Token is still being processed or the user is still to record an avatar, indicating the ‘payload_incomplete’ propety is present in the response and contains information about the completion progress of the avatar.

  • payload_complete[].download_URL (string) – One-time download URL of avatar asset.

  • payload_complete[].export_type (string) – Type of avatar asset, usually indicating file extension.

  • payload_incomplete.completion_progress (integer) – Integer to represent the progress towards completing the processing of the avatar associated with the Export Token. Represents percentage, the value is between 0 and 100. If an avatar has not been associated, the value is -1.

  • payload_incomplete.completion_status (string) – String which indicates the status of the uncompleted avatar associated with the Export Token. Possible values are “no_associated_avatar”, “in_queue”, “processing”, “failed”.

  • payload_incomplete.queue_position (integer) – Integer to represent the position in the avatar processing queue of the avatar associated with the Export Token. If no avatar has been associated or the avatar is not in the queue, value is -1.

Comprehensive Example

This section further expands on the example given inside the Use Case section to include details about the use of API endpoints to integrate Copresence technology.

A video game running on a video game console offers the integration of Copresence avatars during character creation.

When a user desires to use this feature, your backend authenticates with the Copresence backend as a business customer. Your backend then requests the generation of an Export Token through sending a POST request to the /generateExportToken endpoint and receives the token as a response if the request is successful.

The Export Token is then transmitted to the video game console, which displays a custom URL with the Token embedded to the user in the form of a QR code. The Copresence app, or an app clip of it, if it’s not already installed, opens once the user scans the code with their phone.

The user can then record a new avatar using the Copresence app, or choose to use an already existing avatar if the app was already installed. The avatar is then associated with the Export Token by the Copresence backend.

The video game console attempts to retrieve the avatar files through sending a GET request to the /redeemExportToken endpoint. Because the avatar is still processing, the avatar_ready attribute has the false value in the response body, and the payload attribute contains information about the completion state, processing progress, and possibly position in processing queue of the avatar.

One minute later, the video game console attempts to send a GET request to the /redeemExportToken endpoint once again. This time, the avatar is done processing, the avatar_ready attribute is true, and the payload attribute contains URLs to the exported asset files. Since this response returned download URLs, the Export Token which was used is now invalidated and can no longer be used by the console.

The video game console can then download the avatar files. The provided URLs are also invalidated after a short while.