Migrating to Unity SDK v1.0

This guide covers the breaking changes introduced when migrating from the pre‑1.0 Unity SDK to v1.0.

The v1.0 SDK introduces several public API and ABI changes, including renamed types, renamed methods, and new async patterns. This guide focuses on the most common changes your app will encounter.

---

Initialization and readiness

What changed

• PrivyManager.Initialize(...) now returns an IPrivy instance immediately and begins initialization in the background.
• v1.0 removes the PrivyManager.AwaitReady() method.
• The SDK now ensures readiness when your app calls GetAuthState() or GetUser().

Migration

Old (pre‑1.0):

PrivyManager.Initialize(config);
await PrivyManager.AwaitReady();

New (v1.0):

var privy = PrivyManager.Initialize(config);
// Awaiting GetAuthState/GetUser ensures the SDK is fully initialized.
var authState = await privy.GetAuthState();

---

IPrivy API changes (user and auth access)

User access

• v1.0 removes the User property.
• Your app should call await privy.GetUser() instead.

Old (pre‑1.0):

PrivyUser user = PrivyManager.Instance.User;

New (v1.0):

IPrivyUser user = await PrivyManager.Instance.GetUser();

Auth state

• v1.0 removes the AuthState property.
• Your app should call await privy.GetAuthState() instead.

Auth state change callback

• v1.0 removes the SetAuthStateChangeCallback(...) method.
• Your app should subscribe to the AuthStateChanged event instead.

Old:

PrivyManager.Instance.SetAuthStateChangeCallback(state => {
    // handle state
});

New:

PrivyManager.Instance.AuthStateChanged += state => {
    // handle state
};

---

Namespace and type relocations

Many public types now live in more specific namespaces to reduce collisions and improve discoverability.

Old namespace	New namespace	Notes
Privy	Privy.Core	IPrivy, PrivyManager
Privy	Privy.Config	PrivyConfig
Privy	Privy.Auth / Privy.Auth.Models	Auth APIs, IPrivyUser, AuthState
Privy	Privy.Wallets	Embedded wallet APIs
Privy	Privy.Utils	Exceptions, logging, utilities

Update using statements or fully‑qualify types when migrating.

---

Embedded wallet API changes

Wallet collection property

• v1.0 renames EmbeddedWallets to EmbeddedEthereumWallets (the old name is now marked [Obsolete]).

Wallet creation methods

Old	New
CreateWallet(...)	CreateEthereumWallet(...)
CreateWalletAtHdIndex(...)	CreateEthereumWalletAtHdIndex(...)
(new)	CreateSolanaWallet(...)

RPC provider interface

• v1.0 removes IRpcProvider.
• Your app should use IEmbeddedEthereumWalletProvider (in Privy.Wallets) instead.

Example (signing a message)

Old:

IEmbeddedEthereumWallet wallet = await user.CreateWallet();
var response = await wallet.RpcProvider.Request(rpcRequest);

New:

IEmbeddedEthereumWallet wallet = await user.CreateEthereumWallet();
var response = await wallet.RpcProvider.Request(rpcRequest);

---

Exception type changes

v1.0 refactors the exception hierarchy and moves exceptions to Privy.Utils.

Old	New
PrivyException.AuthenticationException	PrivyAuthenticationException
PrivyException.EmbeddedWalletException	PrivyWalletException

Example:

try {
    // ...
} catch (PrivyAuthenticationException ex) {
    // handle auth error
} catch (PrivyWalletException ex) {
    // handle wallet error
}

---

Configuration object changes

PrivyConfig now uses auto-properties and lives in Privy.Config.

Old:

var config = new PrivyConfig {
    AppId = "...",
    ClientId = "...",
    LogLevel = PrivyLogLevel.NONE
};

New:

using Privy.Config;

var config = new PrivyConfig {
    AppId = "...",
    ClientId = "...",
    LogLevel = PrivyLogLevel.None
};

---

Quick migration checklist

1. Update using statements to reference the new namespaces (e.g. Privy.Core, Privy.Auth, Privy.Wallets, Privy.Utils).
2. Replace await PrivyManager.AwaitReady() with await PrivyManager.Instance.GetAuthState() or await PrivyManager.Instance.GetUser().
3. Replace PrivyManager.Instance.User with await PrivyManager.Instance.GetUser().
4. Replace SetAuthStateChangeCallback(...) with AuthStateChanged += ....
5. Replace embedded wallet API calls using CreateWallet / EmbeddedWallets with CreateEthereumWallet / EmbeddedEthereumWallets (and optionally CreateSolanaWallet).
6. Update exception handling to catch PrivyAuthenticationException and PrivyWalletException.

---

For compilation errors after upgrading, search for old types in the project (e.g. IPrivyManager, IRpcProvider, PrivyException.AuthenticationException) and update them as described above. See the Unity SDK setup guide and the Unity changelog for additional reference.