WebRPCs

WebRPCs are a flexible way to integrate external services with Photon Cloud. For instance with a WebRPC, Photon clients can ask the server to fetch data from an external web service.

Contents

• Web Service Basics
• Request
• Response
• Why Choose WebRPC
• Troubleshooting

Web Service Basics

The WebRPC architecture is simple. Photon Servers play a Proxy or Relay role between client and web server. WebRPCs can also be seen as an extension of webhooks or even custom client-driven webhooks.

To use WebRPCs, you need to implement a HTTP based service and configure the BaseURL in the Webhooks section of your application accordingly. Photon Webhooks and WebRPCs share the same BaseURL.

Please take the following development tips into consideration:

• You can use any language or framework or web server to implement the service for the WebRPCs.
• In all cases, try to minimize the data you send to keep things lean and cheap for players.

Back To Top
 

Request

From client side, Photon WebRPC is a Photon operation that is allowed when connected to either Master or Game servers. It requires a URI path string (a.k.a WebRPC method name) and optionally a second argument which contains the data to be sent to the web service (a.k.a WebRPC parameters). Those two arguments can be passed to the PhotonNetwork.WebRPC method.

UriPath is the relative path of the WebRPC which should match the remote procedure name. It is also possible to send parameters in the URL itself. In this case, the query string should be included in the procedure name, appended to the relative path.

When the request is received by Photon servers, the procedure's name will be concatenated to the BaseURL to form the absolute path of the WebRPC's URL before forwarding it to the web service at that same URL.

Since the HTTP request method used is POST, if there are any parameters sent by client, Photon will pass them over as JSON POST data along with default properties:

• AppId: AppId of your application as set from the game client and found in the Dashboard.

• AppVersion: version of your application as set from the game client.

• Region: the region to which the game client is connected to.

• UserId: ID of the actor making the WebRPC.

Any other property found is part of the parameters sent by the client. If the WebRpcParameters type used in client is Dictionary<string, object> then all the key/value pairs will be sent in the root object of the post data. Otherwise, if it is any other JSON valid type, it will be included as a value of a new property RpcParams.

Example 1

Your BaseURL is https://my.service.org and the client calls WebRPC("method?id=1", parameters). The parameters are a Dictionary<string, object> that has a {{"key1": 1}, {"key2": "yx"}, {"key3": true}} as content. In this case, Photon will call https://my.service.org/method?id=1 and additionally POST the JSON:

Example 2

Your BaseURL is https://my.service.org and the client calls WebRPC("method?id=1", parameters). The parameters are an array of objects: object[] { 0, "xy", false }. In this case, Photon will call https://my.service.org/method?id=1 and additionally POST the JSON:

Example 3

Your BaseURL is https://my.service.org and the client calls WebRPC("method?id=1", parameters). The parameters are is a primitive simple type. Let's say a string "test". In this case, Photon will call https://my.service.org/method?id=1 and additionally POST the JSON:

Back To Top
 

Sending Secure Data

WebRPC also offers an option to securely transmit the encrypted object AuthCookie to the web service when available. This can be done by setting the appropriate webflag (SendAuthCookie = 0x02) when calling the WebRPC operation method from client code.

The AuthCookie could be retrieved after a successful authentication against a custom authentication provider. For more information please visit the

custom authentication documentation page.

Back To Top
 

Response

A web service for WebRPCs must respond with a JSON object to allow Photon to send the result back to the clients. The expected response has to include ResultCode, Data and optionally a Message.

The ResultCode should be 0 for OK and any other code for errors. You can make them up to help the client handle the error and adding a readable string message is always a best practice.

The Data can be empty but if you send anything, it must be a valid JSON object.

Example 1

Example 2

Example 3

Back To Top
 

Why Choose WebRPC

Sending HTTP requests can be done without Photon. You can write a HTTP client yourself or use one available from an SDK or a library. However Photon WebRPCs offer more than just that. Here are some of its advantages:

• It may be better to keep all logic inside a single connected client and handle a single "lifecycle" and "state machine". Photon client is what you need in this case.
• WebRPC operation takes care of the JSON serialization for you in both ways.
• "BaseURL" and method names support URL Tags feature.
• You can verify the identity of the client sending the WebRPC using AuthCookie or exchange more sensitive data server-to-server. Read more about how to make use of this feature here.

Back To Top
 

Troubleshooting

Here is the list of the error codes you could get when making WebRPC calls and how to handle each one:

• OperationInvalid (-2)

This generally means that you did not configure or enable WebRPCs server side for your application.

• HttpLimitReached (32745)

This means that you are making too many WebRPC requests per second. Check the error message to know the limit you have exceeded.

• ExternalHttpCallFailed (32744)

This means that something went wrong when communicating with the configured external web service. Find more details in the error message and act accordingly.

To Document Top