OmniGRPC Use Case Guides

This page explains implementation approaches for different purposes, such as authentication, continuous data reception, and streaming. See the Blueprint API Reference for details about each pin.

gRPC has four communication methods. Choose one from the table below according to your purpose. Server Streaming, Client Streaming, and Bidi Streaming are available only in the Full Edition.

On the sample server, you can try each method with the following Methods. Set Service on the Call node to UserService and choose the Method from Method Name in Details.

Authenticate with an access token

1. Create a Channel that uses TLS.
2. Call the login Method with Call gRPC Unary.
3. Save the received access token to a variable.
4. For later calls, set the saved value in Access Token in the Call Options.
5. When the token expires, log in again.

If you want to use the same token for every call on a Channel, you can also set it in the Channel Config’s Access Token. If a value is set in the individual Call Options, that value takes precedence.

Run a Unary RPC

Use Unary for operations that send data once and receive the result once, such as logging in, getting user information, or saving settings.

• Node to use: Call gRPC Unary
• Data to send: Request
• On success: receive Response from On Success
• On failure: receive Status from On Error
• Stop early: call Cancel on the Action returned by the node

If you connect to the same server, reuse the Channel. If you close a screen and no longer need the result, or if you search again with different conditions, Cancel the old call before starting a new one.

Receive data continuously with Server Streaming

Use Server Streaming when the server sends data multiple times in response to a single Request, such as ranking lists, progress updates, monitoring data, or text that an AI is generating.

1. Send a Request with Call gRPC Server Streaming.
2. Update the UI or local state each time On Message Received fires.
3. Confirm normal completion with On Completed.
4. Handle errors with On Error.
5. To close the screen, call Cancel on the Action saved to a variable when the call started.

The game keeps running while On Message Received is being handled. Very heavy processing on every message can make the screen stutter, so split image processing and large calculations into smaller chunks.

The sample WatchUsers receives three records (alice, bob, and carol) and then completes normally.

    sequenceDiagram
	  accTitle: Receiving and ending a Server Streaming call
	  participant BP as Blueprint
	  participant Server as gRPC Server
	  BP->>Server: Send one Request
	  loop Each time data arrives
	    Server-->>BP: On Message Received
	  end
	  alt Normal completion
	    Server-->>BP: On Completed
	  else Error
	    Server-->>BP: On Error
	  end

Send multiple records with Client Streaming

Use Client Streaming when you send data repeatedly and receive the result once at the end, such as registering multiple records or uploading a file in chunks.

1. Start Call gRPC Client Streaming and save the Action output from Then to a variable.
2. Call Send Message on the Action each time you send data.
3. After sending everything, always call Close Send.
4. Receive the server’s result with On Message Received.
5. Finish with On Completed or On Error.

Close Send tells the server that the client has finished sending. If you do not call it, the server may keep waiting for more data and never return a result. After Close Send, you cannot send new data.

    sequenceDiagram
	  accTitle: Sending and ending a Client Streaming call
	  participant BP as Blueprint
	  participant Action as Saved Action
	  participant Server as gRPC Server
	  BP->>Action: Save to a variable from the Call node's Then
	  loop For each item
	    BP->>Action: Send Message (LoginRequest)
	    Action->>Server: Request
	  end
	  BP->>Action: Close Send
	  Action->>Server: Notify that sending is complete
	  Server-->>BP: On Message Received (UploadUsersResponse)
	  Server-->>BP: On Completed

The diagram shows the normal completion path. If Send Message returns false, the message was not accepted. Handle errors with On Error, and if the call is no longer needed, such as when the screen closes, Cancel the Action.

If you send alice and bob to the sample UploadUsers and then call Close Send, you receive Accepted Count = 2 and Summary = uploaded 2 users: alice,bob.

Communicate in both directions with Bidi Streaming

Use Bidi Streaming when you need to send and receive at the same time, such as chat, collaborative editing, or remote control.

1. Start Call gRPC Bidi Streaming and save the Action output from Then to a variable.
2. Call Send Message when needed.
3. Handle On Message Received independently of how many messages you send.
4. Call Close Send when you are done sending.
5. Call Cancel to abort the session itself.

Sending and receiving happen independently. A message you send does not necessarily produce exactly one result next. If you need to match results to specific sends, ask the server team to include an ID in the server-side specification.

Handle normal completion with On Completed and errors with On Error. Receiving continues after Close Send, so keep the Action until you receive one of the end events.

The sample UserLookup returns one UserInfo for each Username sent. For alice, the result is User Id = u-alice and Display Name = alice.

Differences between ending a send, cancelling a call, and closing a connection

If you will keep communicating with the same destination, keep the Channel. When closing a screen or the game, Cancel any unneeded Actions before closing the Channel.

Check server availability

Combine the following features for connection waits on loading screens or for displaying online status.

• Get Channel State: check the current connection state immediately
• Wait for gRPC Channel Connected: wait for a specified time until a connection is possible
• Check gRPC Health: Full Edition only check whether the server can actually process requests

Only Check gRPC Health is a Full Edition feature. Get Channel State and Wait for gRPC Channel Connected are also available in the Free Edition.

Even when the Channel State is Ready, the Service you want may be down. If you need a reliable “online” indicator, check for a successful Health Check as well.

Branch on the Success output of On Connected for Wait for gRPC Channel Connected. When the connection fails, On Connected(false) is called in addition to On Timeout. The API Reference has a table of event behavior.

Retry communication automatically

To retry automatically when the server is temporarily unreachable, configure the Retry Policy in the Channel Config.

• MaxAttempts: maximum number of attempts, including the first one
• InitialBackoff / MaxBackoff: minimum and maximum wait time before retries
• BackoffMultiplier: factor that increases the wait time as failures continue
• RetryableStatusCodes: error types that should be retried automatically
• RetryPolicyServiceName: the fully qualified Service name including the package

For calls where duplicate execution is a problem, such as payments, purchase confirmation, or item grants, check the server-side specification before enabling automatic retries.

Connect to an AI inference service

• Send one image and receive the result: Unary (Free / Full Edition)
• Receive generated text incrementally: Server Streaming (Full Edition only)
• Send audio in chunks and receive the full text at the end: Client Streaming (Full Edition only)
• Voice conversation or interactive sessions: Bidi Streaming (Full Edition only)

If the data is large, such as images or audio, check MaxSendMessageBytes / MaxReceiveMessageBytes and configure compression if needed. Match the values to the server-side settings.

Connect from an Android or iOS device

Android and iOS support is available only in the Full Edition. In the Full Edition, you can use the same Service Assets and Blueprints as on PC. The additional checks for Android and iOS are the destination, network permissions, certificates, and other settings.

On a device, 127.0.0.1 refers to the device itself, not your development PC. To connect to a development server on the LAN, use the PC’s IP address or DNS name that the device can reach.

Use TLS in apps you publish. Connections may also drop when switching between Wi-Fi and mobile networks, or when the app returns from the background. Check the Channel State and show a reconnecting indicator when necessary.