nexo/docs/windows-notification-test-guide.md

# Windows Notification Test Guide

Last verified: 2026-06-02

This guide fixes the preflight contract for Windows notification work before a
Windows test machine, Microsoft account, packaging decision, or real OS
notification UI evidence is available.

Do not commit Microsoft account values, package identity values, signing
certificates, store association files, push credentials, device tokens, auth
tokens, private endpoints, or private host values into tracked docs. Use
placeholders in examples and keep credential files in approved local or
secret-store locations.

## Current Repository State

- `packages/messaging_flutter/pubspec.yaml` does not currently register a
  Windows plugin platform.
- There is no `packages/messaging_flutter/windows/` plugin scaffold and no
  `apps/flutter-test/windows/` host scaffold in the current repository.
- Dart already expects native notification and action channels:
  `com.tokilabs.nexo.messaging/notifications` and
  `com.tokilabs.nexo.messaging/notification_actions`.
- The Windows bridge is therefore not implemented yet. Until it exists, local
  routing can only be tested through Dart unit tests or a future debug injection
  bridge.
- Local routing fixtures live under `apps/flutter-test/windows/Fixtures/*.json`.

The first useful Windows smoke target is:

1. Add a Windows plugin platform registration and generated host scaffold in a
   controlled implementation plan.
2. Register the expected EventChannel and MethodChannel in the Windows plugin.
3. Implement a debug-only local injection path compatible with
   `debugSendNativeEvent`.
4. Choose a notification API path and package identity strategy for the smoke.
5. Map notification activation arguments or user data into the Dart
   `NotificationOpenedEvent` contract.
6. Collect display, click/open routing, lifecycle, and known ACK, dismiss, and
   inline reply gap evidence.

## Platform Registration Contract

Do not add a partial Windows platform entry without the matching source and host
scaffold. A future implementation plan should update these together:

```yaml
flutter:
  plugin:
    platforms:
      windows:
        pluginClass: NexoMessagingPlugin
```

Expected source/host areas for that plan:

- `packages/messaging_flutter/windows/` for the Windows plugin implementation.
- `apps/flutter-test/windows/` for the test host scaffold generated by Flutter.
- `packages/messaging_flutter/pubspec.yaml` for platform registration.
- `apps/flutter-test/README.md` and package docs for smoke instructions.

The current preflight milestone documents this contract only. It does not claim
Windows runtime support.

## Minimum Bridge Contract

The Dart SDK expects the Windows native side to preserve these channel names:

| Channel | Name | Direction | Minimum Windows behavior |
|---|---|---|---|
| EventChannel | `com.tokilabs.nexo.messaging/notifications` | native to Dart | Emit codec-safe maps for notification, open, token, clear, session, and future action-failure events. |
| MethodChannel | `com.tokilabs.nexo.messaging/notification_actions` | Dart to native | Accept SDK action methods used by Dart without crashing the host app. |

Minimum methods for the action channel:

| Method | Minimum preflight result | Production expectation |
|---|---|---|
| `debugSendNativeEvent` | Validate the argument is a map and emit it on the EventChannel. | Debug/test-only injection path. |
| `saveDeviceToken` | Accept and store or no-op a formatted token string without logging secrets. | Store the Windows server-registration token once the platform token source is chosen. |
| `getDeviceToken` | Return the last stored formatted token or null. | Return the current formatted Windows server-registration token. |
| `setAuthToken` | Validate required string arguments and no-op. | Persist token for ACK/reply work only after storage rules are designed. |
| `clearAuthToken` | Validate `serverUrl` and no-op. | Clear persisted token for the server. |
| `setSigningKey` | Validate required string arguments and no-op without persistence. | Persist the signing key only after secure storage rules are designed. |

Fallback boundaries:

- Missing bridge methods should return the Flutter Windows equivalent of
  "not implemented", not a successful placeholder.
- Token, auth, signing-key, ACK, dismiss, and inline reply persistence are not
  implied by this preflight milestone.
- Real notification display and activation handling belong to `Windows 알림 테스트`
  unless a smaller bridge implementation plan explicitly handles them first.

## Notification API Matrix

| Candidate | Packaging fit | Strength | Preflight constraint |
|---|---|---|---|
| Windows App SDK notifications | Best with package identity or sparse package | Modern toast activation path and current Microsoft guidance | Requires Windows App SDK dependency and packaging decision. |
| WinRT toast notifications | Best with MSIX/package identity | Direct OS toast APIs and activation arguments | Packaging/AppUserModelID details must be decided before reliable smoke. |
| Desktop bridge / AppUserModelID shortcuts | Unpackaged desktop fallback | Can support classic desktop notification experiments | More local setup variance and weaker repeatability. |
| Local debug injection only | No packaging requirement | Deterministic EventChannel/opened-routing verification | Does not prove OS display or activation. |

Preflight default: use local debug injection for contract tests, and defer the
Windows App SDK vs WinRT packaging decision to the `Windows 알림 테스트` milestone
or a dedicated implementation plan.

## Payload Mapping

Windows activation payloads map into Dart using the same stable keys as the
Android, iOS, and macOS contracts:

| Payload key | Dart event field | Notes |
|---|---|---|
| `type` | `type` | Use `message` for visible message notifications and `opened` for direct open events. |
| `server_url` | `server_url` | Required before host navigation callbacks can run. |
| `server_id` | `server_id` | Diagnostic and future server URL fallback input. |
| `channel_id` | `channel_id` | Drives `onNavigateToChannel` when thread routing is not selected. |
| `root_id` | `root_id` | Drives `onNavigateToThread` when CRT is enabled. |
| `is_crt_enabled` | `is_crt_enabled` | Accept boolean `true`, string `"true"`, or string `"1"`. |
| `ack_id` | `ack_id` | Preserve for future ACK evidence; do not invent ACK behavior. |
| `post_id` | `post_id` | Preserve for notification identity and future ACK/display evidence. |
| `userInteraction` | `userInteraction` | Set to `true` when a click/open path caused the event. |

Routing expectation:

- Channel fixture: `server_url` and `channel_id` are present, `root_id` is empty
  and `is_crt_enabled` is false, so Dart calls `onNavigateToChannel`.
- Thread fixture: `server_url` and `root_id` are present and
  `is_crt_enabled` is true, so Dart calls `onNavigateToThread`.

## Local Fixtures

Use the fixture files as sanitized payloads for a future debug injection method
or for manual activation/user-data construction during smoke testing:

- `apps/flutter-test/windows/Fixtures/open_channel.json`
- `apps/flutter-test/windows/Fixtures/open_thread.json`

The fixtures intentionally use `https://example.invalid` and smoke IDs. Replace
private runtime values only in local run notes or sanitized evidence.

## Evidence

Use [`windows-notification-smoke-evidence-template.md`](windows-notification-smoke-evidence-template.md)
for Windows runs. Preflight evidence should explicitly separate:

- packaging and identity state
- visible display state
- click/open routing result
- app lifecycle state
- ACK, dismiss, and inline reply implementation gaps

Until the scaffold, bridge, and real OS smoke exist, a valid preflight result
may be "not implemented yet" with a concrete follow-up plan, rather than a
failed runtime claim.