Get started with session manager Extend Override app template

Last updated on August 13, 2025

Overview​

AccelByte Gaming Services (AGS) allows you to implement custom logic to tailor session management strategies, enhancing flexibility and control over game and party sessions. This feature helps you define specific behaviors for session creation, updates, and deletions, ensuring that your unique requirements are met while maintaining seamless integration with the existing session service feature.

This article walks you through the process of setting up custom session override to manage the session data in the following events using the Extend Override app template as an example.

  • OnSessionCreated: the operation when the game session is being created for the first time.
  • OnSessionUpdated: the operation when there is an update or modification to the game session.
  • OnSessionDeleted: the operation when the game session is marked as deleted.
  • OnPartyCreated: the operation when the party session is being created for the first time.
  • OnPartyUpdated: the operation when there is an update or modification to the party session.
  • OnPartyDeleted: the operation when the party session is marked as deleted.

Prerequisites​

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

    a. Bash

    • On Windows WSL2 or Linux Ubuntu:

      bash --version

      GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)
      ...

    • On macOS:

      bash --version

      GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)
      ...

    b. Make

    • On Windows WSL2 or Linux Ubuntu:

      To install from the Ubuntu repository, run sudo apt update && sudo apt install make.

      make --version

      GNU Make 4.3
      ...

    • On macOS:

      make --version

      GNU Make 3.81
      ...

    c. 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
      ...

    d. .NET 8 SDK

    • On Linux Ubuntu:

      To install from the Ubuntu repository, run sudo apt-get update && sudo apt-get install -y dotnet-sdk-8.0.

    • On Windows or macOS:

      Follow Microsoft's documentation for installing .NET on Windows or on macOS.

      dotnet --version

      8.0.104

    e. Postman

    • Use the available binary from Postman.

    f. extend-helper-cli

    g. Local tunnel service that has TCP forwarding capability, such as:

  1. 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. Keep the Client ID and Client Secret.

Clone the app template​

git clone https://github.com/AccelByte/session-manager-grpc-plugin-server-csharp.git

Set up, run, and test an Extend app​

This section covers how to set up, build, run, and then test an Extend app.

Set up the Extend app​

To run the sample custom functions of an Extend app, follow these steps:

  1. Create a docker compose .env file by copying the content of the .env.template file.

    note

    The host OS environment variables have higher precedence compared to the .env file variables. If the variables in the .env file do not seem to take effect properly, check if there are host OS environment variables with the same name. For more details, refer to Docker's documentation about the docker compose environment variables precedence.

  2. Fill in the required environment variables in .env file as shown below:

    AB_BASE_URL=https://test.accelbyte.io     # Base URL of AccelByte Gaming Services environment
    AB_CLIENT_ID='xxxxxxxxxx'                 # Client ID from the Prerequisites section
    AB_CLIENT_SECRET='xxxxxxxxxx'             # Client Secret from the Prerequisites section
    AB_NAMESPACE='xxxxxxxxxx'                 # Namespace ID from the Prerequisites section
    PLUGIN_GRPC_SERVER_AUTH_ENABLED=false     # Enable or disable access token validation
    note

    In this app template, PLUGIN_GRPC_SERVER_AUTH_ENABLED is true by default. If it is set to false, the gRPC server can be invoked without the AccelByte Gaming Services access token. This option is provided for development purposes only. It is recommended to enable gRPC server access token validation in the production environment.

Build the Extend app​

To build this app template, run the following command:

make build

Run the Extend app​

To (build and) run this app template in a container, run the following command:

docker compose up --build

If the docker app is running, we can access it using the port that has been configured in the docker-compose file. For example, in our sample gRPC server app:

...
services:
 app:
   build: .
   ports:
     - "8080:8080"
     - "6565:6565"
...

Two ports are being exposed and the format is host_port:container_port.

  • "8080:8080": This maps port 8080 on your host machine to port 8080 in the container. This means that accessing http://localhost:8080 on your host will route the traffic to port 8080 inside the app container.
  • "6565:6565": This maps port 6565 on the host to port 6565 in the container, allowing access to whatever service is running on that port in the container.

Test the Extend app​

You can test the Extend app in a local development environment or with AGS.

Test in a local development environment​

important

Before testing, make sure PLUGIN_GRPC_SERVER_AUTH_ENABLED is set to false. Otherwise, the gRPC request will be rejected by the gRPC server.

The custom functions in this app template can be tested locally using Postman. To test the Extend app using Postman, follow these steps:

  1. Run the dependency services by following the README.md in the grpc-plugin-dependencies repository.

    warning

    Make sure to start dependency services with mTLS disabled for now: mTLS is currently not supported by AGS, but support for it will be added soon to improve security. If mTLS is enabled, the gRPC client calls without mTLS will be rejected.

  2. Use the following command to run this gRPC server app template:

    docker compose up --build

  3. In Postman, create a new gRPC request and enter localhost:10000 as the server URL. This configuration essentially accesses the gRPC server through an Envoy proxy in dependency services. For more information, refer to Postman's documentation on creating gRPC requests.

  4. In Postman, continue by selecting the OnSessionCreated gRPC call method and click the Invoke button, this will start the stream connection to the gRPC server.

  5. Still in Postman, continue sending parameters to specify the number of players in a match by copying the sample JSON below and clicking Send.

    {
    "session": {
       "session": {
             "id": "sessionid",
             "is_active": true,
             "namespace": "namespace",
             "created_by": "created_by"
          }
       }
    }

    The expected response when successful is for the session to be returned back but will add attribute fields like below:

    {
    "session": {
       "session": {
             "id": "sessionid",
             "is_active": true,
             "namespace": "namespace",
             "created_by": "created_by",
             "attributes": {
                "SAMPLE": "value from GRPC server"
             }
          }
       }
    }

Test with AGS​

To test the app, which runs locally with AGS, the gRPC server needs to be connected to the internet. To do this without requiring public IP, you can use local tunnel service.

  1. Run this app by using the following command:

    docker compose up --build

  2. Expose gRPC server TCP port 6565 in local development environment to the internet. Simplest way to do this is by using local tunnel service provider.

    • Sign in to ngrok and get your authtoken from the ngrok dashboard and set it up in your local environment. And, to expose gRPC server use following command:

      ngrok tcp 6565

    • Or alternatively, you can use pinggy and use only ssh command line to setup simple tunnel. Then to expose gRPC server use following command:

      ssh -p 443 -o StrictHostKeyChecking=no -o ServerAliveInterval=30 -R0:127.0.0.1:6565 tcp@a.pinggy.io

    Please take note of the tunnel forwarding URL, e.g., http://0.tcp.ap.ngrok.io:xxxxx or tcp://xxxxx-xxx-xxx-xxx-xxx.a.free.pinggy.link:xxxxx.

    info

    You may also use other local tunnel service and different method to expose the gRPC server port (TCP) to the internet.

  3. In the Admin Portal, go to the namespace where the Extend app is in and create a session template:

    1. On the sidebar menu, go to Multiplayer > Matchmaking > Session Configuration.
    2. Click on the Add Session Template button. Fill in the required information. For more information, see Create and configure session templates.
    3. Ensure that you enable the Use Custom Session Function option and choose OnSessionCreated as the action for the session template.
    4. Select the Custom URL option and use the tunnel forwarding URL from step 3.
    5. Finish creating the session template or by following next step to simulate the flow.

    Session Template Override

  4. Create an OAuth Client with confidential client type and containing the following permissions:

    • For AGS Private Cloud customers:

      • ADMIN:NAMESPACE:{namespace}:SESSION:CONFIGURATION [CREATE,READ,UPDATE,DELETE]
      • ADMIN:NAMESPACE:{namespace}:INFORMATION:USER:* [DELETE]

    • For AGS Shared Cloud customers:

      • Session -> Custom Configuration (Read, Create, Update, Delete)
      • IAM -> Users (Delete)
    important
    • You will not be able to access the Client Secret after you complete the creation of your IAM client, so make sure you save it.
    • The Oauth Client created in this step is different from the one mentioned in the Prerequisites section. It is required by the Postman collection in the next step to register the gRPC Server URL and also to create and delete test users.

  5. Follow the instructions in the Postman collection (demo/session-manager-demo.postman_collection.json) overview to set up the environment, using the Client ID and Client Secret from the previous step. Pay attention to this app console log when extend app flow is running. At least one of the gRPC Server methods should get called when you run all the requests in the collection.

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.
  5. Set AGS to use 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 > Override.
  3. On the Overridable Feature 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 Overridable Feature app list.

Upload the Extend app​

  1. Set up an IAM client for extend-helper-cli. Create an IAM client with client type confidential and assign the required permissions listed below. Keep a copy of the Client ID and Client Secret.

    • 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)

  2. Export the required environment variables, then build and upload the Extend app container image to AGS using extend-helper-cli.

    • Ensure <project-dir> points to your Extend app project directory
    • The values for <namespace> and <app-name> can be found on the App Detail page of your Extend app
    • Use an appropriate image tag e.g. v0.0.1
    # 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'

    ./extend-helper-cli-linux_amd64 image-upload --login --work-dir <project-dir> --namespace <namespace> --app <app-name> --image-tag v0.0.1
    important
    • We recommend running the above commands in a separate terminal and from a different working directory than the Extend app project. This helps prevent the extend-helper-cli from inadvertently using environment variables intended for the Extend app.
    • If you encounter the following error, see Troubleshooting: Docker login fails for resolution 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.`

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

    image history in AGS Admin Portal

Configure the Extend app​

Before deploying the Extend app that you uploaded, you must configure the environment variables required by the Extend app. In the app's details page, set the following environment variables with the same values that you used to run and test the Extend app locally.

  • AB_CLIENT_ID
  • AB_CLIENT_SECRET
warning

If your Extend Override app is based on app templates before release v2024.02.13, make sure to set PLUGIN_GRPC_SERVER_AUTH_ENABLED environment variable to true. Otherwise, the access token validation in the Extend app is disabled and your Extend app may be accessed without a valid access token.

Since release v2024.02.13, PLUGIN_GRPC_SERVER_AUTH_ENABLED in Extend Override app templates is set to true by default. The access token validation can only be disabled when PLUGIN_GRPC_SERVER_AUTH_ENABLED is explicitly set to false. To align with this, all new Extend apps created through the Admin Portal will not have PLUGIN_GRPC_SERVER_AUTH_ENABLED environment variable set by default. Previously, PLUGIN_GRPC_SERVER_AUTH_ENABLED=false is added on all new Extend apps created through the Admin Portal.

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.

Set AGS to use the Extend app​

In the AGS Admin Portal, go to the namespace you wish to use to create your custom function. On the Admin Portal sidebar, click on Multiplayer > Matchmaking > Session Configuration. On the Session Configurations page, click on the Add Session Template button. When you create your session template, make sure to check the “Use Custom Session Function” selection. Choose the AccelByte Hosted option and select the name of the Extend App you created. Then, click Save to create the new session template.

Session template override with extend app

Next step​

Proceed by modifying the Extend Override app template to implement your own custom logic. For more details, see here.

Last updated on
On this page