Broadcast notifications #

Broadcasts push a notification to every connected session of a kind. Use player broadcasts to alert players of upcoming maintenance, signal that new content is available, or relay any event all connected clients should react to. Use partner broadcasts to reach every connected game server.

A service broadcasts with one of three Service methods:

Each method delivers to sessions connected to the backend the calling service runs on. A game service reaches sessions on the game backend; a social service reaches sessions on the social backend.

Operators can also send player broadcasts directly through the notifyAllActiveSessionsOperatorV1 endpoint without writing any service code.

All examples on this page use the broadcastToPlayersV1 RPC from the DemoService reference service introduced in Custom services.

Define the notification #

A broadcast notification is a proto message with message type NOTIFICATION and the session type of its recipients: PLAYER, PARTNER, or OPERATOR. It is defined alongside the RPC that triggers it:

demoServiceRpc.proto

package unicorn.demo;

message BroadcastToPlayersV1Request {
    option (pragma.pragma_session_type) = OPERATOR;
    option (pragma.pragma_message_type) = REQUEST;

    string message = 1;
}

message BroadcastToPlayersV1Response {
    option (pragma.pragma_session_type) = OPERATOR;
    option (pragma.pragma_message_type) = RESPONSE;
}

message BroadcastToPlayersV1Notification {
    option (pragma.pragma_session_type) = PLAYER;
    option (pragma.pragma_message_type) = NOTIFICATION;

    string message = 1;
}

The notification message name determines the generated SDK event name. BroadcastToPlayersV1Notification produces OnBroadcastToPlayersV1 in the Unreal SDK.

Broadcast from a service #

Build the notification proto and pass it to notifyAllActivePlayers:

DemoService.kt

package unicorn.demo

import pragma.OperatorSession
import pragma.rpcs.PragmaRPC
import pragma.rpcs.RoutingMethod
import pragma.rpcs.SessionType
import unicorn.demo.DemoServiceRpc.BroadcastToPlayersV1Notification
import unicorn.demo.DemoServiceRpc.BroadcastToPlayersV1Request
import unicorn.demo.DemoServiceRpc.BroadcastToPlayersV1Response

//...

@PragmaRPC(SessionType.OPERATOR, RoutingMethod.SESSION_PRAGMA_ID)
suspend fun broadcastToPlayersV1(session: OperatorSession, request: BroadcastToPlayersV1Request): BroadcastToPlayersV1Response {
    val notification = BroadcastToPlayersV1Notification.newBuilder()
        .setMessage(request.message)
        .build()

    notifyAllActivePlayers(notification)

    return BroadcastToPlayersV1Response.getDefaultInstance()
}

To broadcast to partner or operator sessions, call notifyAllActivePartners or notifyAllActiveOperators the same way, with a notification whose session type matches.

Broadcasts don’t return a result. If delivery fails, the failure is logged and the calling RPC continues. Sessions that connect after a broadcast don’t receive it, so if late joiners need the same state, pair the broadcast with a fetch when the client connects.

Broadcast from an operator #

Operators can send player broadcasts directly using notifyAllActiveSessionsOperatorV1 without writing service code:

curl --location 'http://localhost:10000/v1/rpc' \
--write-out '\nHTTP %{http_code}\n' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <operator-token>' \
--data '{
    "requestId": 1,
    "type": "PlayerSessionRpc.NotifyAllActiveSessionsOperatorV1Request",
    "payload": {
        "notification": {
            "type": "BroadcastToPlayersV1Notification",
            "payload": {
                "message": "Maintenance will start in one hour"
            }
        }
    }
}'

The type field inside notification is the proto message name. The payload contains the notification fields.

Handle notifications #

On the client, subscribe to the notification event on the generated raw service class. The SDK delivers the typed notification whenever the server broadcasts it:

RpcBasics.cpp

#include "Dto/UnicornDemoServiceRaw.h"

//...

Player->Api<UUnicornDemoServiceRaw>().OnBroadcastToPlayersV1.AddWeakLambda(this,
	[this](FPragma_Demo_BroadcastToPlayersV1Notification Notification, const FPragmaMessageMetadata&)
	{
		Handler->OnBroadcastReceived(Notification.Message);
	});

Subscribe during initialization (e.g., in BeginPlay) so the handler is in place before any broadcasts arrive. Use AddWeakLambda to tie the subscription to the subscribing object’s lifetime.

Configure delivery batching #

Each instance of a session service delivers a broadcast to the sessions it holds in batches, so a large broadcast doesn’t flood the node. Instances deliver in parallel, so shard-wide throughput is roughly the batch size per interval multiplied by the number of game/social gateway instances. Batches pace when sends start; the next batch doesn’t wait for the previous one to finish.

Configure player broadcast batching through the player session configs:

game:
  serviceConfigs:
    GamePlayerSessionConfig:
      notifyAllActiveSessionsBatchSize: 500
      notifyAllActiveSessionsBatchIntervalMillis: 1000
social:
  serviceConfigs:
    SocialPlayerSessionConfig:
      notifyAllActiveSessionsBatchSize: 500
      notifyAllActiveSessionsBatchIntervalMillis: 1000

Partner broadcasts use the same settings on the partner session configs. Their interval defaults to 0, so batches are sent without pausing; partner connection counts are typically small enough not to need pacing. Raise it if you run enough game servers for an unpaced broadcast to matter.

game:
  serviceConfigs:
    GamePartnerSessionConfig:
      notifyAllActiveSessionsBatchIntervalMillis: 100
social:
  serviceConfigs:
    SocialPartnerSessionConfig:
      notifyAllActiveSessionsBatchIntervalMillis: 100
telemetry:
  serviceConfigs:
    TelemetryPartnerSessionConfig:
      notifyAllActiveSessionsBatchIntervalMillis: 100

Operator broadcasts use a batch size of 500 with no interval and aren’t configurable.

Related topics #

• Custom services for creating the service that triggers broadcasts.