# AI Usage For XmobiTea DeviceId

Use this file when you need normal integration code or the common decision guide. Skip it when the task already points to exact API or behavior details.

## Need-Based Routing

| Need | Use |
| --- | --- |
| Normal integration code | this file |
| Exact supported API or symbols | `AI_API_REFERENCE.md` |
| Platform storage, reset, logging, and lifetime details | `AI_BEHAVIOR.md` |
| Package guardrails | `AGENTS.md` |

## Contract

- Namespace: `XmobiTea.MiniDeviceId`
- Correct call: `CXDevice.GetDeviceId()`
- Return value: opaque `string`
- Scene object required: no
- Initialization required: no
- Settings asset required: no
- Singleton or manager required: no
- Same persistence on every platform: no

## Choose The API

| Need | Correct call | Notes |
| --- | --- | --- |
| Get the package identifier | `CXDevice.GetDeviceId()` | Use this for all supported targets |
| Reuse the value many times | Cache caller-side after `CXDevice.GetDeviceId()` | Especially useful outside startup paths |
| Reset WebGL generated ID | `PlayerPrefs.DeleteKey("MiniDeviceId_DeviceId"); PlayerPrefs.Save();` | Use only if product logic explicitly wants a reset |
| Access the native keychain bridge directly | No supported public call | Use `CXDevice.GetDeviceId()` only |

## Copy Pattern

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

public sealed class DeviceIdExample : MonoBehaviour
{
    private string deviceId;

    private void Awake()
    {
        deviceId = CXDevice.GetDeviceId();
    }

    private void Start()
    {
        Debug.Log(deviceId);
    }
}
```

## Platform Model

| Target group | What `CXDevice.GetDeviceId()` returns |
| --- | --- |
| Default targets | `SystemInfo.deviceUniqueIdentifier` |
| WebGL | A GUID generated once and stored in `PlayerPrefs` key `MiniDeviceId_DeviceId` |
| Apple-path assembly (`iOS`, `tvOS`, `macOSStandalone`) | `uuid` from the native keychain bridge JSON payload; empty `uuid` falls back to `SystemInfo.deviceUniqueIdentifier` and is written back with user slot `"0"` |

The native JSON payload fields are `userId` and `uuid`; the native keychain entries use keys `UserID` and `UserUUID`. The `Runtime/iOS` asmdef is selected for `macOSStandalone`, but this repo does not include a macOS standalone native bridge under `Plugins/iOS`.

Treat the value as an identifier string, not as a guaranteed hardware identity.

## Hard No

- Do not generate scene bootstrap code for this package.
- Do not add a manager, singleton, prefab, `Resources` asset, or initialization call.
- Do not call `Implement.Get()` from consumer code, even if it is visible.
- Do not reference `CXKeyChain`; it is internal to the package.
- Do not use `CustomId` as a consumer-facing data model.
- Do not assume WebGL returns a hardware-backed ID.
- Do not claim the package ships a macOS standalone native bridge just because the asmdef includes `macOSStandalone`.
- Do not assume reinstall, browser storage clear, app data clear, or keychain reset behaves the same on all targets.
- Do not promise security, hashing, consent, analytics compliance, or anti-fraud guarantees.

## Need More

- Exact public and implementation-visible symbols: `AI_API_REFERENCE.md`
- Platform persistence, reset, logging, and performance notes: `AI_BEHAVIOR.md`
- Agent guardrails: `AGENTS.md`