📘

This feature requires the Immerse SDK Enterprise Edition

This is different to the free Immerse SDK. Contact [email protected] if you require access.

Understand the difference between the Free and Enterprise SDK

The Immerse Platform and SDK allows messages to be sent to and from users in a session. This feature can also be used to preserve a session's state.

Anatomy of a Message

Messages can contain a lot of information. We have designed them so that they are as flexible as possible. The developer has complete control over what goes in a message's payload.

When receiving a message, a user is presented with a Message object which contains the following information.

📘

Pro Tip: The message ID is 16 bytes and can be used to serialize more information than a simple number

Example: Hello World

This is a simple example of how to send and receive a message. It consists of three main parts.

1. Define your Message

In the provided example we are using message type 1000.

📘

Any ushort value greater than the reserved range of 0-999 can be used

To test this script, create a new Message Definition with the following configuration:

• Message Type: 1000
• Profile: Participant
• Is Persisted: ❌
• Broadcast to Self: ✔

2. Listen for Incoming Messages

It is important to listen for a message before you expect to receive it. In this example, we start listening immediately on Start . Here we register a handler HandleMessage for the message type. This method will be called each time we receive a message of the specified type.

3. Send a Message

To send a message, you must first be connected. In the example below we are using the Yield Instruction WaitForConnectionStatus to wait until we are connected to the multi-user service.

using System.Collections;
using System.Text;
using ImmerseSDK.PlatformServices;
using ImmerseSDK.PlatformServices.Multiuser;
using ImmerseSDK.PlatformServices.Multiuser.Messaging;
using UnityEngine;

public class HelloWorld : MonoBehaviour
{    
    [Tooltip("Message type to use")]
    public ushort MessageType = 1000;
 
    [Tooltip("The message we are sending")]
    public string MessageText = "Hello World";
    
    private IEnumerator Start()
    {
        // Start listening for incoming messages
        MessageRegistry.Register(MessageType, HandleMessage);
        
        // Wait until we are connected before attempting to send a message
        yield return new WaitForConnectionStatus(ConnectionStatus.Connected);
        SendMessage();
    }

    /// <summary>
    /// Send the message
    /// </summary>
    [ContextMenu("Send Message")]
    private void SendMessage()
    {
        // Encode MessageText to a byte array and send our message
        var payload = Encoding.UTF8.GetBytes(MessageText);
        Networking.Client.SendMessage(MessageType, default, payload);
        Debug.Log("Message Sent");
    }
    
    /// <summary>
    /// Handles incoming messages
    /// </summary>
    /// <param name="message">Message received</param>
    private void HandleMessage(Message message)
    {
        // GetPayloadAsString will read the payload as a UTF8 string
        var messageText = message.GetPayloadAsString(); 
        Debug.Log("Message Received: " + messageText);
    }
}