# XmobiTea DeviceId

Static device identifier facade for Unity with platform-specific backing behavior.

## Need-Based Routing

Choose by current need. Open only the smallest file that answers it.

| Need | Use |
| --- | --- |
| Generate normal integration code | `AI_USAGE.md` |
| Check exact supported API | `AI_API_REFERENCE.md` |
| Understand platform storage and reset behavior | `AI_BEHAVIOR.md` |
| Package guardrails for agents | `AGENTS.md` |

## Contract

- Namespace: `XmobiTea.MiniDeviceId`
- Supported entry point: `CXDevice.GetDeviceId()`
- Return type: `string`
- Scene setup: none
- Initialization: none
- Settings asset: none
- Public manager or singleton: none
- Result semantics: opaque identifier string with platform-dependent backing source and persistence behavior

Use this package when code needs one call site for a device/app identifier across Unity targets.

## Correct Usage

```csharp
using UnityEngine;
using XmobiTea.MiniDeviceId;

public sealed class DeviceIdExample : MonoBehaviour
{
    private void Start()
    {
        var deviceId = CXDevice.GetDeviceId();
        Debug.Log(deviceId);
    }
}
```

If the value is used repeatedly in a hot path, cache it in caller code after the first read.

## Platform Summary

| Target group | Backing source |
| --- | --- |
| Default targets | `SystemInfo.deviceUniqueIdentifier` |
| WebGL | Generated GUID stored in `PlayerPrefs` key `MiniDeviceId_DeviceId` |
| Apple-path assembly (`iOS`, `tvOS`, `macOSStandalone`) | Native keychain bridge JSON fields `userId` and `uuid`; returns `uuid`. When `uuid` is empty, the package falls back to `SystemInfo.deviceUniqueIdentifier`, writes it back with user slot `"0"`, and logs the save |

The returned value should not be treated as a guaranteed hardware ID or as having identical reset behavior on every platform.

Native keychain entries use keys `UserID` and `UserUUID`. The `Runtime/iOS` asmdef is also selected for `macOSStandalone`, but this package does not ship a macOS standalone native bridge under `Plugins/iOS`.

## Package Files

- `Runtime/CXDevice.cs`: supported public facade
- `Runtime/Default/DefaultImplement.cs`: default target implementation
- `Runtime/WebGL/WebGLImplement.cs`: WebGL implementation
- `Runtime/iOS/iOSImplement.cs`: Apple-path implementation assembly selected for `iOS`, `tvOS`, and `macOSStandalone`
- `Runtime/iOS/CXKeyChain.cs`: internal native bridge wrapper
- `Plugins/iOS/*`: Objective-C keychain plugin sources; implementation files are imported for iOS and tvOS

## Package Metadata

- Package name: `com.xmobitea.changx.mini-deviceid`
- Display name: `XmobiTea DeviceId`
- Unity version: `2022.3`
- License: `Apache-2.0`