Create a service extension app for Vivox

Last updated on November 25, 2024

Overview​

The AccelByte Gaming Services (AGS) Extend service allows you to develop a service extension application for Vivox, enabling seamless integration between AGS, Vivox, and game clients. A Vivox service extension app will generate signed Vivox tokens that game clients need to interact with Vivox. Each token is valid for 90 seconds, requiring game clients to regularly request a new token from the service.

Prerequisites​

  1. Windows 11 WSL2 or Linux Ubuntu 22.04 or macOS 14+ with the following tools installed:

    a. Docker (Docker Desktop 4.30+/Docker Engine v23.0+)

    • On Linux Ubuntu:

      1. To install from the Ubuntu repository, run sudo apt update && sudo apt install docker.io docker-buildx docker-compose-v2.
      2. Add your user to the docker group: sudo usermod -aG docker $USER.
      3. Log out and log back in to allow the changes to take effect.

    • On Windows or macOS:

      Follow Docker's documentation on installing the Docker Desktop on Windows or macOS.

      docker version

      ...
      Server: Docker Desktop
         Engine:
         Version:          24.0.5
      ...

    b. extend-helper-cli

  2. Access to the AGS Admin Portal environment.

    • Base URL: <your environment's domain URL>

      • Example for AGS Shared Cloud customer: https://spaceshooter.prod.gamingservices.accelbyte.io
      • Example for AGS Private Cloud customer: https://dev.customer.accelbyte.io

    • Create a game namespace if you don't have one yet. Take note of the namespace ID.

    • Create an OAuth Client with confidential client type containing the following permissions:

      • For AGS Private Cloud customers:

        • ADMIN:ROLE [READ]
        • ADMIN:NAMESPACE:{namespace}:NAMESPACE [READ]

      • For AGS Shared Cloud customers:

        • IAM > Roles (Read)
        • Basic > Namespace (Read)

        Keep the Client ID and Client Secret.

  3. Your Vivox configuration.

    • Vivox application-specific issuer name
    • Vivox domain name
    • Vivox signing key

Clone the app repository​

git clone https://github.com/AccelByte/extend-rtu-vivox-authorization-service-go

Deploy in AGS​

Deploying an Extend app in AGS involves the following steps in the Admin Portal:

  1. Create the Extend app.
  2. Upload the Extend app.
  3. Configure the Extend app.
  4. Deploy the Extend app.

Create the Extend app​

  1. In the AGS Admin Portal, go to the namespace where you wish to create your Extend Override app.
  2. On the sidebar menu, under ADD-ONS, go to Extend > Service Extension.
  3. On the Service Extension page, click on the + Create New button.
  4. On the Create App form, provide a name and description (optional) for your Extend app.
  5. Click Create. Your new Extend app is added to the Service Extension app list.

Upload the Extend app​

  1. Set up an OAuth Client for extend-helper-cli. Create an OAuth Client with confidential client type and containing the following permission:

    • For AGS Private Cloud customers:
      • ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS [READ]
      • ADMIN:NAMESPACE:{namespace}:EXTEND:APP [READ]
    • For AGS Shared Cloud customers:
      • Extend > Extend app image repository access (Read)
      • Extend > App (Read)

    Keep a copy of the Client ID and Client Secret.

  2. Copy the extend-helper-cli command to perform docker login on the Extend app details page under Repository Authentication Command.

    Repository authentication command in Admin Portal

  3. Export the required environment variables and perform docker login using extend-helper-cli. Run this command:

    # Your AGS environment base URL, e.g., https://spaceshooter.prod.gamingservices.accelbyte.io, https://dev.accelbyte.io, etc.
    export AB_BASE_URL='https://xxxxxxxxxx'
    # Client ID of OAuth Client for extend-helper-cli (from step 1)
    export AB_CLIENT_ID='xxxxxxxxxx'     
    # Client Secret of OAuth Client for extend-helper-cli (from step 1)
    export AB_CLIENT_SECRET='xxxxxxxxxx'        

    # The command to perform docker login (from step 2)
    ./extend-helper-cli-linux_amd64 dockerlogin --namespace <game namespace> --app <app name> --login
    important

    AccelByte recommends running the above commands in a separate terminal and in a different working directory than the Extend app project. This is to reduce the chances of the extend-helper-cli picking up the environment variables for the Extend app project instead.

    The output of a successful login looks similar to the following:

    INFO[0000] signing in to https://dev.accelbyte.io 
    INFO[0001] getting docker credentials...                
    WARNING! Your password will be stored unencrypted in /home/xyz-abc/.docker/config.json.
    Configure a credential helper to remove this warning. See
    https://docs.docker.com/engine/reference/commandline/login/#credentials-store

    Login Succeeded
    note

    If you get the following error, refer to the Troubleshooting: Docker login fails section for troubleshooting steps.

    Error saving credentials: error storing credentials - err: exit status 1, out: `error storing credentials - err: exit status 1, out: `The stub received bad data.`

  4. Upload the Extend app container image to AGS using extend-helper-cli image-upload command. You can specify your extend app project by using -w parameter. For the image tag, you can put v0.0.1. For example:

    ./extend-helper-cli-linux_amd64 image-upload -n <game namespace> -a <app name> -w <extend app source dir> -t <image tag>
    info

    You can use the --login parameter to log in and upload the image simultaneously using a single command. Refer to the extend-helper-cli README page for more details.

    If your images are successfully uploaded, you will see an image with version v0.0.1 on the Image Version History page.

    Extend app image history

Configure the Extend app​

Before deploying the uploaded Extend app, you must configure the environment variables required by the app. In the app's details page, set the following environment variables with the values prepared in the Prerequisites section.

  • AB_CLIENT_ID
  • AB_CLIENT_SECRET
  • VIVOX_ISSUER
  • VIVOX_DOMAIN
  • VIVOX_SIGNING_KEY

Deploy the Extend app​

To deploy the Extend app, click Deploy Latest Image. Wait until the app status updates to RUNNING, which indicates that your Extend app is successfully deployed.

Run sample game client​

AccelByte provides you a sample game client to try Vivox authentication service. Follow these steps:

  1. Clone the project.

    git clone https://github.com/AccelByte/extend-vivox-authorization-sample-game-unreal

  2. Configure the AGS SDK for Unreal. Follow the steps in the Configure the AGS Game SDK for the IAM client section in the Install the AGS Game SDK guide.

  3. Configure the Vivox Unreal SDK.

    1. Set the values for VIVOX_VOICE_SERVER, VIVOX_VOICE_DOMAIN, VIVOX_ISSUER in the VivoxGameInstance.cpp file with values that are found in the Vivox Credentials in your Unreal Dashboard project.
    2. Set the value for VIVOX_TOKEN_PROVIDER_URL in the VivoxTokenProvider.cpp
    3. Locate and modify Token Provider Url field and Inspector field.

  4. Open the project (Client/ShooterGame.uproject) in your IDE.

  5. Build and package the for Windows (64-bit).

  6. Launch one or more instances of the build. The executable name should be ShooterGame.exe.

  7. Have one client host and others join.

Next step​

If you want to customize the Vivox service extension app to meet your requirements, refer to the Create a service extension app guide.

Last updated on

On this page