From 9d9bb2bf2c48907bb617e60fd06a52698d12804e Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Sat, 17 Oct 2026 15:32:32 +0100 Subject: [PATCH 1/2] docs: refresh README --- README.md | 193 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 124 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index 41460ac..1dce2dc 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,9 @@ # Appwrite Unity SDK -![License](https://img.shields.io/github/license/appwrite/sdk-for-unity.svg?style=flat-square) +![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg?style=flat-square) ![Version](https://img.shields.io/badge/api%20version-2.5.0-blue.svg?style=flat-square) ![Unity](https://img.shields.io/badge/Unity-2021.3%2B-blue.svg?style=flat-square) -[![Build Status](https://img.shields.io/travis/com/appwrite/sdk-for-unity?style=flat-square)](https://travis-ci.com/appwrite/sdk-for-unity) -[![Twitter Account](https://img.shields.io/twitter/follow/appwrite?color=00acee&label=twitter&style=flat-square)](https://twitter.com/appwrite) +[![X Account](https://img.shields.io/badge/follow-%40appwrite-000000?logo=x&style=flat-square)](https://x.com/appwrite) [![Discord](https://img.shields.io/discord/564160730845151244?label=discord&style=flat-square)](https://appwrite.io/discord) **This SDK targets Appwrite server version 2.5.x as shipped on Appwrite Cloud.** Self-hosted releases can lag behind Cloud — if you run an older self-hosted build, use a matching older SDK from [previous releases](https://github.com/appwrite/sdk-for-unity/releases) when APIs differ. @@ -14,123 +13,183 @@ Appwrite is an open-source backend as a service server that abstracts and simpli ## Installation +Requires Unity 2021.3 or later. Installing from a git URL also requires [Git](https://git-scm.com/downloads) on your `PATH`. + ### Unity Package Manager (UPM) -1. Open Unity and go to **Window > Package Manager**. -2. Click the **+** button and select **Add package from git URL**. -3. Enter the following URL: +1. In Unity, open **Window > Package Manager**. +2. Click the **+** button and select **Add package from git URL** (**Install package from git URL** in Unity 6). +3. Enter the following URL and click **Add** (**Install** in Unity 6): -```sh +```text https://github.com/appwrite/sdk-for-unity.git#0.10.0 ``` -4. Click **Add**. +The `#0.10.0` suffix pins the package to a release. Change it to any released tag, or omit it to track the latest commit on the default branch. + +You can also add the package to `Packages/manifest.json` directly: -The `#0.10.0` suffix pins the package to a specific release. Change it to any released tag, or omit `#0.10.0` to track the latest commit on the default branch. +```json +{ + "dependencies": { + "io.appwrite.unity": "https://github.com/appwrite/sdk-for-unity.git#0.10.0" + } +} +``` -### Manual Installation +### Install from disk -Download the latest release from [GitHub](https://appwrite.io/releases/latest) and import the Unity package into your project. +1. Download the source code archive of a release from [GitHub](https://github.com/appwrite/sdk-for-unity/releases) and extract it. +2. In **Window > Package Manager**, click the **+** button and select **Add package from disk** (**Install package from disk** in Unity 6). +3. Select the `package.json` file in the extracted folder. +## OAuth on Android + +OAuth sign-in returns to your app through the `appwrite-callback-` URL scheme. When you build for Android, the package registers this scheme on the Unity activity for the project ID set on each `AppwriteConfig` asset in your project, so you do not need to edit any manifest. + +If you create the client in code without a `AppwriteConfig` asset, enable **Custom Main Manifest** in **Project Settings > Player > Android > Publishing Settings** and add this intent filter to the Unity activity in `Assets/Plugins/Android/AndroidManifest.xml`, replacing `` with your project ID: + +```xml + + + + + + +``` ## Getting Started -Before you begin, create an Appwrite project and add a Unity platform in your Appwrite Console. +### Install dependencies -This SDK requires the following Unity packages and libraries: +The SDK depends on two packages that are installed separately: -- [**UniTask**](https://github.com/Cysharp/UniTask): For async/await support in Unity. -- [**NativeWebSocket**](https://github.com/endel/NativeWebSocket): For WebSocket realtime subscriptions. -- **System.Text.Json**: For JSON serialization, provided as a DLL in the project. +- [**UniTask**](https://github.com/Cysharp/UniTask) for async/await support. +- [**NativeWebSocket**](https://github.com/endel/NativeWebSocket) for realtime subscriptions. -After installing the SDK, open **Appwrite → Setup Assistant** in Unity and install the required dependencies. +When you first import the SDK, the **Appwrite Setup Assistant** opens and offers to install them. You can reopen it at any time from **Appwrite > Setup Assistant**. The SDK's runtime code stays disabled until UniTask is installed. `System.Text.Json` and its dependencies ship with the SDK as DLLs. -### Configure the SDK +### Configure your project -Create an Appwrite configuration using the **QuickStart** window in the **Appwrite Setup Assistant**, or through **Appwrite → Create Configuration**. +Create a project in the [Appwrite Console](https://cloud.appwrite.io/). Find your endpoint and project ID in the project's **Settings** page. -### Using AppwriteManager +If you build for WebGL, add a **Web** platform to your project with the hostname that serves your build, so Appwrite accepts requests from it. + +Then create an `AppwriteConfig` asset with **Appwrite > Create Configuration**, or click **Setup Current Scene** in the Setup Assistant to create the asset and add an `AppwriteManager` to the open scene. Set the endpoint (for example `https://.cloud.appwrite.io/v1`), your project ID, and the services you want `AppwriteManager` to create. + +### Make your first request with AppwriteManager + +`AppwriteManager` creates the client and the services selected in your configuration, and can open the realtime connection. ```csharp -[SerializeField] private AppwriteConfig config; -private AppwriteManager _manager; +using Appwrite; +using Appwrite.Services; +using Cysharp.Threading.Tasks; +using UnityEngine; -private async UniTask ExampleWithManager() +public class AppwriteExample : MonoBehaviour { - _manager = AppwriteManager.Instance ?? new GameObject("AppwriteManager").AddComponent(); - _manager.SetConfig(config); + [SerializeField] private AppwriteConfig config; + + private RealtimeSubscription subscription; - var success = await _manager.Initialize(needRealtime: true); - if (!success) + private async void Start() { - Debug.LogError("Failed to initialize AppwriteManager"); - return; - } + var manager = AppwriteManager.Instance; + if (manager == null) + { + manager = new GameObject("AppwriteManager").AddComponent(); + } - var client = _manager.Client; - var pingResult = await client.Ping(); - Debug.Log($"Ping result: {pingResult}"); + manager.SetConfig(config); - var realtime = _manager.Realtime; - var subscription = realtime.Subscribe( - new[] { "databases.*.collections.*.documents" }, - response => + if (!await manager.Initialize(needRealtime: true)) { - var eventName = response.Events != null && response.Events.Length > 0 - ? response.Events[0] - : "unknown"; - - Debug.Log($"Realtime event: {eventName}"); + Debug.LogError("Failed to initialize AppwriteManager"); + return; } - ); - // Keep a reference to close the subscription when your MonoBehaviour is destroyed. - // subscription.Close(); + var tablesDB = manager.GetService(); + var rows = await tablesDB.ListRows( + databaseId: "", + tableId: ""); + Debug.Log($"Found {rows.Total} rows"); + + subscription = manager.Realtime.Subscribe( + Channel.TablesDB("").Table("").Row(), + response => Debug.Log($"Realtime event: {response.Events[0]}")); + } + + private void OnDestroy() + { + subscription?.Close(); + } } ``` -### Using Client directly +`GetService()` throws if the service is not selected in your `AppwriteConfig`. + +### Using the client directly + +You can also create a client and services yourself, without `AppwriteManager`: ```csharp -private async UniTask ExampleWithDirectClient() -{ - var client = Client.From( - projectId: "", - endpoint: "https://.cloud.appwrite.io/v1", - endpointRealtime: "wss://.cloud.appwrite.io/v1"); +var client = Client.From( + projectId: "", + endpoint: "https://.cloud.appwrite.io/v1"); - var pingResult = await client.Ping(); - Debug.Log($"Direct client ping: {pingResult}"); -} +var account = new Account(client); +var session = await account.CreateAnonymousSession(); +Debug.Log($"Signed in as {session.UserId}"); ``` -You can also create authenticated clients with `Client.FromSession` or `Client.FromImpersonation` when those authentication flows are needed. +`Client.FromSession`, `Client.FromJWT` and `Client.FromImpersonation` create clients that are already authenticated. + +### OAuth sign-in + +`account.CreateOAuth2Session()` opens the provider's sign-in page and waits for Appwrite to redirect back to your app on the `appwrite-callback-` URL scheme. Appwrite accepts this scheme for your project without extra Console setup, but your build must handle it: + +- **Android**: add an intent filter for the scheme to your project's main manifest at `Assets/Plugins/Android/AndroidManifest.xml` (enable **Custom Main Manifest** under **Project Settings > Player > Android > Publishing Settings**): + + ```xml + + + + + + + ``` + +- **iOS**: add `appwrite-callback-` to **Supported URL schemes** under **Project Settings > Player > iOS > Other Settings**. +- **WebGL**: the sign-in page opens in the same tab, so register a **Web** platform for your build's hostname. ### Error handling +The SDK throws an `AppwriteException` when a request fails. It exposes `Message`, `Code`, `Type`, and `Response` properties that you can use to inspect the error. + ```csharp try { - var result = await client.Ping(); + var user = await account.Get(); } catch (AppwriteException ex) { - Debug.LogError($"Appwrite Error: {ex.Message}"); - Debug.LogError($"Status Code: {ex.Code}"); + Debug.LogError($"Appwrite error: {ex.Message}"); + Debug.LogError($"Status code: {ex.Code}"); Debug.LogError($"Response: {ex.Response}"); } ``` -## Preparing Models for Databases API +### Preparing models for TablesDB -When working with the Databases API in Unity, models should be prepared for serialization using the System.Text.Json library. System.Text.Json uses CLR property names by default unless a naming policy is configured. If your project or SDK configuration serializes property names differently from your Appwrite collection attributes, this can cause errors due to mismatches between serialized property names and actual attribute names in your collection. +The SDK serializes request data with `System.Text.Json` and converts property names from `PascalCase` to `camelCase`. If your table's column names are not in `camelCase`, the serialized names will not match your columns. -To avoid this, add the `JsonPropertyName` attribute to each property in your model class to match the attribute name in Appwrite: +Add the `JsonPropertyName` attribute to each property of your model so it serializes to the column name: ```csharp using System.Text.Json.Serialization; -public class TestModel +public class Movie { [JsonPropertyName("name")] public string Name { get; set; } @@ -140,20 +199,16 @@ public class TestModel } ``` -The `JsonPropertyName` attribute ensures your data object is serialized with the correct attribute names for Appwrite databases. - ### Learn more You can use the following resources to learn more and get help: -- 🚀 [Getting Started Tutorial](https://appwrite.io/docs/getting-started-for-client) +- 🚀 [Appwrite Quick Starts](https://appwrite.io/docs/quick-starts) - 📜 [Appwrite Docs](https://appwrite.io/docs) - 💬 [Discord Community](https://appwrite.io/discord) -- 🧰 [Appwrite SDK Generator](https://github.com/appwrite/sdk-generator) - ## Contribution -This library is auto-generated by the Appwrite [SDK Generator](https://github.com/appwrite/sdk-for-unity). To learn how you can help improve this SDK, please check the [contribution guide](https://github.com/appwrite/sdk-for-unity/blob/master/CONTRIBUTING.md) before sending a pull request. +This library is auto-generated by the Appwrite [SDK Generator](https://github.com/appwrite/sdk-generator). To learn how you can help improve this SDK, please check the [contribution guide](https://github.com/appwrite/sdk-generator/blob/main/CONTRIBUTING.md) before sending a pull request. ## License From 8e3fe6a4ae9fc8eaf49384695b04a30a871f2bb6 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Sat, 17 Oct 2026 17:48:10 +0100 Subject: [PATCH 2/2] docs: describe OAuth setup for the released package --- README.md | 18 +++--------------- 1 file changed, 3 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 1dce2dc..3ac1a7a 100644 --- a/README.md +++ b/README.md @@ -45,9 +45,7 @@ You can also add the package to `Packages/manifest.json` directly: ## OAuth on Android -OAuth sign-in returns to your app through the `appwrite-callback-` URL scheme. When you build for Android, the package registers this scheme on the Unity activity for the project ID set on each `AppwriteConfig` asset in your project, so you do not need to edit any manifest. - -If you create the client in code without a `AppwriteConfig` asset, enable **Custom Main Manifest** in **Project Settings > Player > Android > Publishing Settings** and add this intent filter to the Unity activity in `Assets/Plugins/Android/AndroidManifest.xml`, replacing `` with your project ID: +OAuth sign-in returns to your app through the `appwrite-callback-` URL scheme. Enable **Custom Main Manifest** in **Project Settings > Player > Android > Publishing Settings** and add this intent filter to the Unity activity in `Assets/Plugins/Android/AndroidManifest.xml`, replacing `` with your project ID: ```xml @@ -149,19 +147,9 @@ Debug.Log($"Signed in as {session.UserId}"); `account.CreateOAuth2Session()` opens the provider's sign-in page and waits for Appwrite to redirect back to your app on the `appwrite-callback-` URL scheme. Appwrite accepts this scheme for your project without extra Console setup, but your build must handle it: -- **Android**: add an intent filter for the scheme to your project's main manifest at `Assets/Plugins/Android/AndroidManifest.xml` (enable **Custom Main Manifest** under **Project Settings > Player > Android > Publishing Settings**): - - ```xml - - - - - - - ``` - +- **Android**: see [OAuth on Android](#oauth-on-android). - **iOS**: add `appwrite-callback-` to **Supported URL schemes** under **Project Settings > Player > iOS > Other Settings**. -- **WebGL**: the sign-in page opens in the same tab, so register a **Web** platform for your build's hostname. +- **WebGL**: not supported. The sign-in page replaces your build in the same tab, and a browser cannot return to it on the callback scheme, so the call never completes. Use another sign-in method, such as email and password, in WebGL builds. ### Error handling