Skip to main content

User Management

Each end user of your application is identified by a player ID. This page covers how player IDs work, how to persist them, and how to manage multiple characters.

Player ID Concept​

The playerId is a string that uniquely identifies an end user. It serves two purposes:

  1. Conversation persistence -- The same playerId + characterId pair always resumes the same conversation. The character remembers everything from previous sessions.
  2. Memory isolation -- Each player has their own memory graph. The character builds a separate understanding of each user.

Player IDs can be any string up to 128 characters.

Setting the Player ID​

In the Inspector​

Set the Player Id field on the EstuaryCharacter component. If left blank, a default is generated from SystemInfo.deviceUniqueIdentifier:

player_<first 8 chars of device ID>

In Code​

character.PlayerId = "user_12345";

Set this before calling Connect() or before Start() if AutoConnect is enabled.

Persisting Player IDs​

For consistent memory across app sessions, persist the player ID locally.

Using PlayerPrefs​

using UnityEngine;
using Estuary;

public class PlayerIdManager : MonoBehaviour
{
    private const string PLAYER_ID_KEY = "estuary_player_id";

    [SerializeField] private EstuaryCharacter character;

    void Awake()
    {
        // Load or generate player ID
        string playerId = PlayerPrefs.GetString(PLAYER_ID_KEY, "");

        if (string.IsNullOrEmpty(playerId))
        {
            playerId = $"player_{System.Guid.NewGuid():N}";
            PlayerPrefs.SetString(PLAYER_ID_KEY, playerId);
            PlayerPrefs.Save();
        }

        character.PlayerId = playerId;
    }
}

Using Your Auth System​

If your application has its own user authentication, use your user ID:

// After your auth flow completes
character.PlayerId = myAuthSystem.CurrentUserId;

Multiple Characters​

A single scene can have multiple EstuaryCharacter components, each connected to a different character on the Estuary platform.

Registering Characters​

Characters register with EstuaryManager automatically on Start(). The first character registered becomes the active character -- the one that receives bot responses and voice audio.

Switching Characters​

// Switch the active character
EstuaryManager.Instance.SetActiveCharacter(otherCharacter);

Switching the active character while connected will disconnect and reconnect with the new character's ID.

Listening for Character Changes​

EstuaryManager.Instance.OnActiveCharacterChanged += (previous, current) =>
{
    Debug.Log($"Switched from {previous?.CharacterId} to {current?.CharacterId}");
};

Session Information​

After connecting, session details are available on the character:

character.OnConnected += (SessionInfo session) =>
{
    Debug.Log($"Session ID: {session.SessionId}");
    Debug.Log($"Conversation ID: {session.ConversationId}");
    Debug.Log($"Character ID: {session.CharacterId}");
    Debug.Log($"Player ID: {session.PlayerId}");
};

// Or access later
var session = character.CurrentSession;

The ConversationId persists across sessions for the same player+character pair. Use it to fetch conversation history via the REST API.

Resetting a Conversation​

To start a fresh conversation (clearing all memory), use a new player ID:

character.PlayerId = $"player_{System.Guid.NewGuid():N}";
character.Connect();

The character will treat this as a completely new user with no history.

Next Steps​

Last updated