diff --git a/README.md b/README.md index b3f06b6..8ab3c51 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,13 @@ -# SmartThings Developer Skills +# SmartThings Developer AI Skills > **📢 Notice** > Features, documentation, and skill behaviors may change. Your feedback via GitHub Issues is highly appreciated! -A collection of AI skills that accelerates SmartThings device integration. It supports the full lifecycle, from initial code generation to WWST certification. +A collection of AI-powered skills that accelerates SmartThings device integration. It supports the full lifecycle, from initial code generation to WWST certification. ## 📖 Overview -This project provides AI skills for developers who want to integrate devices into the SmartThings ecosystem. Each skill improves development productivity with step-by-step guidance, best practices, code generation, and debugging support. +This project provides SmartThings Developer AI Skills for developers who want to integrate devices into the SmartThings ecosystem. Each skill improves development productivity with step-by-step guidance, best practices, code generation, and debugging support. ### SmartThings Device Integration Types @@ -27,14 +27,14 @@ SmartThings supports three integration types depending on the device characteris - SmartThings Developer account ([Sign up](https://developer.smartthings.com/)) - SmartThings CLI (optional, recommended) -- A coding assistant environment such as Claude Code, Codex, or Antigravity +- An AI Assistant with file system manipulation capabilities (e.g., Claude Code, Cursor) ### How To Use These Skills -These skills can be used with AI assistants that support MCP (Model Context Protocol), such as Cline, Cursor, and Claude Desktop. +SmartThings Developer AI Skills can be used with AI assistants that support file system operations and custom skill loading. 1. **Installation** - Install the full skill directory under `skills/` that matches your AI development environment. + Install the full SmartThings Developer AI Skills directory under `skills/` to your AI Assistant's skill directory. You can instruct your AI assistant to install the skills directly by pasting the following prompt: @@ -42,7 +42,7 @@ These skills can be used with AI assistants that support MCP (Model Context Prot Install Agent Skills from https://github.com/SmartThingsCommunity/wwst-skills. ``` - > **💡 Installation Tip**: If your AI Coding Assistant does not support automatic skill installation, refer to the [Open Agent Skills specification](https://agentskills.io/client-implementation/adding-skills-support#step-1-discover-skills) or your AI Coding Assistant's Skills documentation for manual setup instructions. + > **💡 Installation Tip**: If your AI Assistant does not support automatic skill installation, refer to your AI Assistant's documentation for manual skill installation instructions, or add the `skills/` directory to your skill configuration path. **Uninstall** - Delete the copied skill directory, or remove the reference from your tool's configuration. @@ -68,7 +68,7 @@ These skills can be used with AI assistants that support MCP (Model Context Prot ## 📚 Skill List -This English README currently documents the following skills under `skills/`. +This English README currently documents the following SmartThings Developer AI Skills under `skills/`. ### 1. Cloud Connected (Schema App) @@ -137,11 +137,28 @@ This skill explains SmartThings device onboarding QR requirements across Matter, - Developers validating QR payload fields before publication - Partners handling Matter, Zigbee 3.0, Direct Connected, or Mobile Connected onboarding flows +### 5. App-to-App Account Linking + +> **Skill**: `smartthings-app-to-app-linking-developer` + +This skill guides mobile app developers in implementing seamless App-to-App Account Linking between native Android/iOS applications and the SmartThings app, specifically for Cloud Connected (ST-Schema) integrations. + +**Key features** +- Associated Domains and Digital Asset Links (`assetlinks.json` / AASA) validation and configurations +- Native Android Manifest intent filters and Kotlin code templates for intent parsing and callback assembly +- Xcode capabilities and Swift UserActivity delegate handling for iOS callback routing +- Support instructions for new vs. already certified Schema Apps +- Developer Mode setup and end-to-end device testing workflows + +**Best fit** +- Mobile application developers building native smart home apps for Android and iOS +- Teams integrating ST-Schema apps looking to enable App-to-App account linking + --- ## ⚠️ Limitations and Notes -These skills provide development guidance and code generation support for SmartThings device integration. Before applying their output, verify the relevant content with the official SmartThings documentation, Developer Console, SmartThings CLI, and real-device testing. +SmartThings Developer AI Skills provide development guidance and code generation support for SmartThings device integration. Before applying their output, verify the relevant content with the official SmartThings documentation, Developer Console, SmartThings CLI, and real-device testing. --- diff --git a/skills/smartthings-app-to-app-linking-developer/SKILL.md b/skills/smartthings-app-to-app-linking-developer/SKILL.md new file mode 100644 index 0000000..96a3898 --- /dev/null +++ b/skills/smartthings-app-to-app-linking-developer/SKILL.md @@ -0,0 +1,81 @@ +--- +name: smartthings-app-to-app-linking-developer +description: Guides developers through setting up and implementing SmartThings App-to-App Account Linking for Android and iOS mobile devices, specifically for Cloud Connected (ST-Schema) integrations. Enforces dynamic lookup of the official documentation as the source of truth. +metadata: + version: "2026-06-09" +--- + +# SmartThings App-to-App Account Linking Guide + +This skill helps developers implement seamless App-to-App Account Linking between their native mobile applications (Android/iOS) and the SmartThings app. + +> [!IMPORTANT] +> - App-to-App Account Linking is supported exclusively for **Cloud Connected (ST-Schema)** integrations. +> - **Prerequisite**: This is **optional, but recommended when applicable** — if the developer's native Android/iOS app can already authenticate the user (i.e., it can substitute for the browser-based OAuth login screen), implementing this is recommended for the smoother UX/higher onboarding completion it gives users. It requires a Schema App to already be registered in the SmartThings Developer Console (created via the **`smartthings-cloud-connected-developer`** skill's Step 4, `04-hosting-and-registration.md`). If the user has not registered a Schema App yet, direct them to that skill first and return here afterward. +> - **Source of Truth Rule**: The AI agent **MUST** fetch and read the live content of `https://developer.smartthings.com/docs/devices/cloud-connected/app-to-app-linking` at the beginning of the task to retrieve the absolute source-of-truth code blocks, intent parsing logic, and regional redirect URIs. + +## Core Operating Principles + +1. **Source of Truth Dynamic Lookup**: Always fetch `https://developer.smartthings.com/docs/devices/cloud-connected/app-to-app-linking` to read the official Kotlin/Swift code implementations, query parameter names, and callback domains. Do not output stale code or static assumptions; instead, inspect the official documentation dynamically during execution. +2. **Language Adaptation**: Respond in the developer's language of choice (e.g., Korean, English) and reuse existing context. +3. **Phase-by-Phase Progression**: App-to-App linking requires both environment configuration and code changes. Progress step-by-step with the user, ensuring domain configurations are set before code is written. +4. **Dynamic Callback Enforcement**: Always instruct the developer to parse parameters (`client_id`, `state`, `redirect_uri`, `response_type`) from incoming intents dynamically. Do not allow hardcoding of callback URLs, as SmartThings hosts regional domains. When returning the authorization code, the query parameter key must be strictly fixed to `code`. +5. **Certified/Published App Rule**: If the Schema App is already certified/published, the developer must contact SmartThings support/WWST team to apply the App-Link/Universal Link rather than modifying it directly. +6. **Merge Digital Asset Files**: When generating `assetlinks.json` or `apple-app-site-association`, do not overwrite existing files. Read the existing file first, parse its JSON, and append/merge the new SmartThings association block to preserve other integrations (e.g., Google/Apple login or other deep links). +7. **User Consent & Disclosure Enforcement & Checklists**: Focus on guiding the implementation using detailed checklists (Android/iOS Phase 2 & 3 guidelines) rather than copy-pasting local code templates. Before issuing an authorization code, the partner app **MUST** display a clear consent screen explaining that the user's devices will be linked to and controllable by the SmartThings app. Explicit user action is required, and the cancel path must map to `error=unauthorized`. +8. **Vibe Coding Compliance & Spec Adherence**: When generating or writing integration codes dynamically (often termed "Vibe Coding" or AI code generation), the AI assistant and developer must strictly adhere to the technical specifications defined in the Phase 2 & 3 checklists. Do not omit critical security and integration details (such as `client_id` validation, `state` parameter consistency, returning the authorization code strictly via the `code` query parameter key, and `universalLinksOnly` options) for the sake of simplified code output. Every checkpoint in the reference checklists must be rigorously met to prevent runtime failures and comply with WWST certification standards. + +## Persona and Goals +This skill supports: +- Native mobile developers (Kotlin, Swift) integrating their smart home application with the SmartThings ecosystem. +- Developers looking to improve user onboarding completion rates by avoiding browser-based OAuth flows. + +> [!IMPORTANT] +> **UX Responsibility**: App-to-App Account Linking transfers authority over the user's physical devices to SmartThings. The partner app is responsible for presenting a proper consent UI to the user before completing the OAuth flow. The AI assistant must remind developers of this UX obligation at the implementation phase. + +## Specialized Debugging Summary (Quick Reference) + +| Symptom | Cause | Resolution | +| :--- | :--- | :--- | +| SmartThings app falls back to browser OAuth | Native app not installed, or OS verification of App Links/Universal Links failed. | Check `assetlinks.json` or `apple-app-site-association` hosting and format. | +| Account linking completes but state is missing | Partner app did not return the exact `state` token received from SmartThings. | Ensure incoming `state` param is saved and appended to callback. | +| Redirect back to SmartThings fails | Invalid or hardcoded callback URL. | Decode the incoming `redirect_uri` param dynamically using UTF-8. | + +## Code Writing Reference (Deep Link Parameters) + +Refer to the official documentation for parsing logic. Expect these query parameters from the incoming link: +* `client_id` (String): Validate this against your known Client ID for security. +* `response_type` (String): Fixed to `code`. The parameter key name you must use when returning your authorization code is strictly fixed to `code`. +* `state` (String): Session identifier. Must be passed back exactly as-is. +* `redirect_uri` (String): Encoded SmartThings callback URL. Decode using UTF-8 before appending parameters. + +## Overall Process (App-to-App Linking Sequence) + +### Phase 1: Environment Setup and Domain Verification +Establish secure association between your app domain and the mobile app binary. +**➔ Read `references/01-environment-setup.md` to guide the user.** + +### Phase 2: Android App Links Implementation +Configure your Android app Manifest, register intent filters, parse incoming params, and trigger login. +**➔ Read `references/02-android-implementation.md` to write/guide the code.** + +### Phase 3: iOS Universal Links Implementation +Configure iOS Associated Domains, handle user activities in Swift, and redirect back. +**➔ Read `references/03-ios-implementation.md` to write/guide the code.** + +### Phase 4: SmartThings Console Registration & Testing +After code implementation, the developer **must** register the App-to-App Link URLs in the SmartThings Developer Console **before** any device testing. + +**Console navigation path**: +[SmartThings Developer Console](https://developer.smartthings.com/console) → **Device Integrations** → **Schema Apps** tab → Select your Schema App → **App-to-App Linking (optional)** section + +> The AI assistant **must walk the developer through this console step** after Phase 2/3 code implementation is complete, and **before** instructing them to run device tests. Do not skip directly to testing. + +**➔ Read `references/04-registration-and-testing.md` to guide the user.** + +--- + +## Key Reference Links (Global References) + +* Official App-to-App Linking Guide: `https://developer.smartthings.com/docs/devices/cloud-connected/app-to-app-linking` (Source of Truth) +* **Related skill (prerequisite)**: `smartthings-cloud-connected-developer` — use this first to create/register the Schema App (OAuth client, `connector.json`, Console registration) that App-to-App Linking attaches to. diff --git a/skills/smartthings-app-to-app-linking-developer/references/01-environment-setup.md b/skills/smartthings-app-to-app-linking-developer/references/01-environment-setup.md new file mode 100644 index 0000000..4ea0889 --- /dev/null +++ b/skills/smartthings-app-to-app-linking-developer/references/01-environment-setup.md @@ -0,0 +1,99 @@ +# Phase 1: Environment Setup + +Establish secure domain-to-app associations for Android App Links and iOS Universal Links. + +--- + +## 💡 Concept Overview: App Links & Universal Links + +> [!IMPORTANT] +> **Key Integration Rules**: +> * **ST-Schema Only**: App-to-App Account Linking is supported **exclusively** for Cloud Connected (ST-Schema) integrations. +> * **Browser Fallback**: If the partner application is not installed on the user's mobile device, the SmartThings App automatically falls back to standard web browser-based OAuth. + +* **Definition**: OS-level features (Android App Links / iOS Universal Links) that open your native app directly when a web URL (HTTP/HTTPS) is clicked, skipping browser selection popups. +* **Why use them instead of custom URI schemes (e.g., `myapp://`)?**: + 1. **Security**: The OS verifies domain ownership via `assetlinks.json`/AASA to prevent malicious apps from hijacking your links. + 2. **Smooth Fallback**: If the app is not installed, the OS cleanly opens the website in Safari/Chrome instead of failing. + +### Account Linking Flows + +The diagram below outlines the overall OAuth authorization and token exchange process, highlighting the secure App-to-App flow (shaded in blue) and the traditional App-to-Web fallback: + +```mermaid +sequenceDiagram + autonumber + participant ST as SmartThings + participant STApp as SmartThings App + participant YourApp as Your App + participant YourAuth as Your Auth Server + participant YourConnector as Schema App + + alt App to App case + rect rgb(204, 242, 255) + STApp->>YourApp: Launch your app to get an authorization code + Note over YourApp: Agree user consent + YourApp->>YourAuth: Request an authorization code in secure path + YourAuth-->>YourApp: Authorization code + YourApp-->>STApp: Authorization code + end + else App to Web case + STApp->>YourAuth: Request authorization code (via Webview) + Note over YourAuth: Sign in / Agree user consent + YourAuth-->>STApp: Authorization code + end + + STApp->>ST: Redirect authorization code + ST->>YourAuth: Request access token (using auth code) + YourAuth-->>ST: Access token + ST->>YourConnector: Interactions such as discovery with access token +``` + +--- + +> [!IMPORTANT] +> **Domain Ownership `{your-domain}`**: +> All occurrences of `{your-domain}` (or `yourdomain.com`) in the paths and console registration parameters refer to the developer's **own verified server domain** (e.g., `yourcompany.com`). +> * **Ownership**: Must be fully owned and controlled by your organization. +> * **Security**: Must support SSL/TLS over HTTPS (HTTP is not permitted by mobile operating systems). +> * **Consistency**: The domain and path prefix must match exactly across the console settings, mobile source codes, and hosted digital asset files. + +## 🤖 Android App Links Setup + +* **File Target**: `https://{your-domain}/.well-known/assetlinks.json` +* **Requirements**: Serve over HTTPS, response Content-Type `application/json`, HTTP `200 OK` status, and no redirects. +* **Source of Truth**: Refer to the **Account Linking on Android > Prerequisites** section of the [Official App-to-App Documentation](https://developer.smartthings.com/docs/devices/cloud-connected/app-to-app-linking#prerequisites) for the verified JSON payload structure, Play Console signing key details, and relation attributes. + +--- + +## 🍏 iOS Universal Links Setup + +* **File Target**: `https://{your-domain}/.well-known/apple-app-site-association` (no extension) +* **Requirements**: Serve over HTTPS, response Content-Type `application/json`, HTTP `200 OK` status, and no redirects. +* **Source of Truth**: Refer to the **Account Linking on iOS > Prerequisites** section of the [Official App-to-App Documentation](https://developer.smartthings.com/docs/devices/cloud-connected/app-to-app-linking#prerequisites-1) to retrieve the required `apple-app-site-association` JSON schema, App ID formatting (`TeamID.BundleID`), and components mapping. + +--- + +## 🔑 Preparation Checklist (Domain Files & Console) + +| OS | Parameter | Purpose / Target Destination | +| :--- | :--- | :--- | +| **Android** | Package Name | Defined in `assetlinks.json` on your server (`applicationId` in `build.gradle`) | +| | SHA-256 Fingerprint | Defined in `assetlinks.json` on your server (from app signing key) | +| | Android App-to-App Link | Entered in SmartThings Console (e.g., `https://yourdomain.com/smartthings-auth`) | +| **iOS** | Bundle ID | Defined in `apple-app-site-association` (AASA) on your server | +| | Team ID | Defined in `apple-app-site-association` (AASA) on your server (10-char Apple Team ID) | +| | iOS App-to-App Link | Entered in SmartThings Console (e.g., `https://yourdomain.com/smartthings-auth`) | +| | App Store ID | (Optional) Entered in SmartThings Console for App Store redirection | + +--- + +## 🛠️ File Generation Support + +The AI assistant can automatically generate domain association files directly in your workspace. Provide the following parameters to request generation: +* **Android (`assetlinks.json`)**: Package Name & SHA-256 fingerprint. +* **iOS (`apple-app-site-association`)**: App Bundle ID & Apple Developer Team ID. + +> [!IMPORTANT] +> **Preserving Existing Domain Associations (Merge Rule)**: +> If you already have existing domain verification files, the AI assistant must **not** overwrite them. It will read the existing JSON contents and **merge** the new SmartThings credentials into the existing arrays/dictionaries, ensuring that existing configurations (e.g. Google Login, Apple Sign In, or other custom App Links) remain functional. diff --git a/skills/smartthings-app-to-app-linking-developer/references/02-android-implementation.md b/skills/smartthings-app-to-app-linking-developer/references/02-android-implementation.md new file mode 100644 index 0000000..47f520e --- /dev/null +++ b/skills/smartthings-app-to-app-linking-developer/references/02-android-implementation.md @@ -0,0 +1,53 @@ +# Phase 2: Android Coding Checkpoints + +When implementing Android App Links for SmartThings App-to-App Linking, the AI assistant must implement and verify the following checkpoints: + +--- + +## 🔑 Coding Checkpoints + +* **[ ] Manifest Intent-Filter URL Matching**: + Configure the `` in `AndroidManifest.xml` with `android:autoVerify="true"` for the authentication Activity. The `` element must define the exact `scheme` (`https`), `host` (your domain), and `pathPrefix` (e.g., `/smartthings-auth`) that matches the **Android App-to-App Link** registered in the SmartThings Developer Console. +* **[ ] Intent Query Parameter Parsing**: + Extract the incoming deep link URL from the intent using `intent.data` or `intent.dataString`. Parse this URL (e.g., via `Uri.parse()`) and dynamically retrieve the standard OAuth parameters: + - `client_id`: The client ID of your integration. + - `redirect_uri`: The target callback URL hosted by SmartThings. + - `response_type`: Expected token key (usually `code`). + - `state`: Verification token to prevent CSRF. + Use standard Android `Uri` query parser methods (e.g., `getQueryParameter("key")`) to extract these values. +* **[ ] Client ID Security Check**: + Validate the incoming `client_id` parameter against the expected Integration Client ID. If they mismatch, terminate the authentication immediately to prevent link hijacking. +* **[ ] User Consent & Disclosure Screen** ⚠️: + Before presenting the login screen or issuing any authorization code, **display a clear consent screen** informing the user that: + - Their account will be linked to the SmartThings app. + - SmartThings will be able to discover and control their registered devices. + - They can revoke this access at any time via their account settings. + + The consent screen must require an **explicit user action** (e.g., tapping "Agree" / "Authorize" button). If the user declines or cancels, trigger the **failure callback** (`error=unauthorized`). +* **[ ] Dynamic Callback Assembly & UTF-8 Handling**: + Do not hardcode the SmartThings callback URL. Extract the `redirect_uri` query parameter from the incoming deep link. Because the Android `Uri` parser automatically URL-decodes query values, parse the extracted `redirect_uri` string to construct the final callback target domain and path. +* **[ ] Fixed Callback Query Key ('code')**: + Append the authorization code to the success callback strictly using the `code` query parameter key (e.g., `?code=AUTH_CODE`). Do not dynamically map other key names based on `response_type`. +* **[ ] State Parameter Match**: + Retrieve the exact `state` token received from the incoming intent, and return it exactly as-is under the query parameter key `state` in the callback URL. +* **[ ] Failure Handoff Handling**: + If authentication fails, is rejected, or is cancelled, build the redirect callback URL by appending the `error` query parameter with a descriptive error string (e.g., `error=unauthorized`) and the exact `state` received, and redirect back to SmartThings. +* **[ ] Native Redirection via ACTION_VIEW**: + To hand control back to the SmartThings app, construct the callback URL (e.g., `https://c2c-us.smartthings.com/c2c-app-to-app-account-linking?state=...&code=...` or with `error=unauthorized`) and launch it using a native Intent with `Intent.ACTION_VIEW`. Do not load this URL in a WebView. + +--- + + +## 💻 CLI Verification (Testing your App Link) + +To test if your Android app is configured correctly to receive the App Link without needing the SmartThings app, run the following ADB command in your terminal: + +```bash +adb shell am start -W -a android.intent.action.VIEW \ + -d "https://{your-domain}/smartthings-auth?client_id={your-client-id}&response_type=code&state=xyz123&redirect_uri=https%3A%2F%2Foauth.smartthings.com" \ + {your-package-name} +``` + +*Replace `{your-domain}`, `{your-client-id}`, and `{your-package-name}` with your actual parameters. If the setup is correct, this command will launch your authentication Activity directly on the connected device.* + + diff --git a/skills/smartthings-app-to-app-linking-developer/references/03-ios-implementation.md b/skills/smartthings-app-to-app-linking-developer/references/03-ios-implementation.md new file mode 100644 index 0000000..d8afdbf --- /dev/null +++ b/skills/smartthings-app-to-app-linking-developer/references/03-ios-implementation.md @@ -0,0 +1,56 @@ +# Phase 3: iOS Coding Checkpoints + +When implementing iOS Universal Links for SmartThings App-to-App Linking, the AI assistant must implement and verify the following checkpoints: + +--- + +## 🔑 Coding Checkpoints + +* **[ ] Associated Domains & AASA Path Matching**: + Enable the `Associated Domains` capability in Xcode and add the entry `applinks:yourdomain.com`. The `apple-app-site-association` file on your server must allow the matching path (e.g., `/smartthings-auth`) that matches the **iOS App-to-App Link** registered in the SmartThings Developer Console. +* **[ ] Universal Link Interception**: + Intercept incoming Universal Links inside your app delegate entry points. + - If using `AppDelegate`, override `application(_:continue:restorationHandler:)` and verify that `userActivity.activityType` is equal to `NSUserActivityTypeBrowsingWeb`. + - If using `SceneDelegate`, check `scene(_:willConnectTo:options:)` (for launch-time links) or override `scene(_:continue:)` (for runtime links). +* **[ ] Query Parameter Parsing**: + Extract the incoming Universal Link URL from `userActivity.webpageURL`. Parse this URL (e.g., via Swift's `URLComponents(url:resolvingAgainstBaseURL:)` API) and dynamically retrieve the standard OAuth parameters: + - `client_id`: The client ID of your integration. + - `redirect_uri`: The target callback URL hosted by SmartThings. + - `response_type`: Expected token key (usually `code`). + - `state`: Verification token to prevent CSRF. +* **[ ] Client ID Security Check**: + Validate the incoming `client_id` query parameter against the expected Integration Client ID. If they mismatch, abort the process immediately to prevent link hijacking. +* **[ ] User Consent & Disclosure Screen** ⚠️: + Before presenting the login screen or issuing any authorization code, **display a clear consent screen** informing the user that: + - Their account will be linked to the SmartThings app. + - SmartThings will be able to discover and control their registered devices. + - They can revoke this access at any time via their account settings. + + The consent screen must require an **explicit user action** (e.g., tapping "Agree" / "Authorize" button). If the user declines or cancels, trigger the **failure callback** (`error=unauthorized`). +* **[ ] Dynamic Callback Assembly**: + Do not hardcode the callback URL. Dynamically build the final redirect target by appending parameters to the received `redirect_uri` parameter. Because Swift's `URLComponents` automatically handles URL-decoding, use it to safely build the final redirect URL. +* **[ ] Fixed Callback Query Key ('code')**: + Append the authorization code to the success callback strictly using the `code` query parameter key (e.g., `?code=AUTH_CODE`). Do not dynamically map other key names based on `response_type`. +* **[ ] State Parameter Match**: + Retrieve the exact `state` parameter value from the incoming activity, and return it exactly as-is under the query parameter key `state` in the callback. +* **[ ] Failure Handoff Handling**: + If authentication fails, is rejected, or is cancelled, build the redirect callback URL by appending the `error` query parameter with a descriptive error code string (e.g., `error=unauthorized`) and the exact `state` received, then redirect back to SmartThings. +* **[ ] Universal Link Redirection via Native API**: + Open the dynamically constructed redirection URL using Apple's native opening API: + `UIApplication.shared.open(url, options: [UIApplication.OpenExternalURLOptionsKey.universalLinksOnly: true]) { success in ... }` + Setting `universalLinksOnly` to `true` is critical to force iOS to route the link directly back to the native SmartThings app instead of launching Safari. Implement a completion handler to handle navigation failures gracefully. + +--- + + +## 💻 CLI Verification (Testing your Universal Link) + +To test if your iOS app is configured correctly to receive the Universal Link on an iOS Simulator, run the following command in your terminal: + +```bash +xcrun simctl openurl booted "https://{your-domain}/smartthings-auth?client_id={your-client-id}&response_type=code&state=xyz123&redirect_uri=https%3A%2F%2Foauth.smartthings.com" +``` + +*Replace `{your-domain}` and `{your-client-id}` with your actual parameters. If the setup is correct, the booted simulator will immediately launch your iOS application and pass the activity to your handler.* + + diff --git a/skills/smartthings-app-to-app-linking-developer/references/04-registration-and-testing.md b/skills/smartthings-app-to-app-linking-developer/references/04-registration-and-testing.md new file mode 100644 index 0000000..97dbbac --- /dev/null +++ b/skills/smartthings-app-to-app-linking-developer/references/04-registration-and-testing.md @@ -0,0 +1,51 @@ +# Phase 4: Registration and Testing + +Procedures for Developer Console configurations and end-to-end device testing workflows. + +--- + +## ⚙️ 1. Developer Console Setup + +In the [SmartThings Developer Console](https://developer.smartthings.com/console), navigate as follows: + +**Console navigation path**: +**Device Integrations** → **Schema Apps** tab → Select your Schema App → **App-to-App Linking (optional)** section + +Configure the following fields in that section: + +* **Android App-to-App Link**: Enter the base App Link URL of your Android app that handles the authentication flow (e.g., `https://{your-domain}/smartthings-auth`). SmartThings will launch this URL and append the required OAuth query parameters to it. +* **iOS App-to-App Link**: Enter the base Universal Link URL of your iOS app that handles the authentication flow (e.g., `https://{your-domain}/smartthings-auth`). SmartThings will launch this URL and append the required OAuth query parameters to it. + + +> [!IMPORTANT] +> **URL Matching & Domain Ownership Reminder**: +> * **Own Domain**: The `{your-domain}` placeholder in the URLs above must be replaced with the developer's **own verified HTTPS domain** (e.g., `yourcompany.com`). +> * **Exact Match**: The registered App-to-App Link URLs here **must exactly match** the scheme, host, and path prefix patterns configured in your mobile apps during **Phase 2 (Android)** and **Phase 3 (iOS)**. If they mismatch, the deep link handoff will fail and fall back to the browser. + + +### B. Already Certified/Published Schema Apps +> [!CAUTION] +> If the Schema App has **already been verified/certified**, settings are locked and cannot be edited in the console. +> +> **Action Required**: You must **contact the SmartThings / WWST support team** directly and submit a request to apply the App-Link / Universal Link configurations to your live app. + +--- + +## 🔍 2. Pre-Testing Diagnostics + +* **Android Link Validation**: Refer to Google Digital Asset Links API to check the mapping. +* **iOS Link Validation**: Verify that your AASA file is served over HTTPS with no redirects and a strict `application/json` Content-Type header. + +--- + +## 📱 3. Device Testing Procedures + +To test the App-to-App Account Linking flow on a physical device, you must enable Developer Mode on your SmartThings mobile app. + +* **Developer Mode Activation**: Refer to the [SmartThings Developer Mode Guide](https://developer.smartthings.com/docs/devices/enable-developer-mode) for the detailed step-by-step procedure to enable Developer Mode on the SmartThings app. +* **No Invitations**: App-to-App Account Linking testing is **not** supported via Schema Invitations. +* **Core Testing Scenarios**: Verify the following integration flows: + - **Normal Success Handoff**: The native app launches, completes authentication, and returns the authorization code to SmartThings via the `code` query parameter. + - **Failure / Cancel Handoff**: If the user declines or authentication fails, return `error=unauthorized` back to SmartThings. + - **App Not Installed Fallback**: Verify that the flow falls back to standard browser OAuth when the native app is not installed. +* **Market/Production Signing Verification**: Before submitting the app for WWST certification, verify the flow using a build signed with your **Production/Market keys** (Google Play App Signing key or iOS Distribution profile). Make sure the production SHA-256 fingerprint or App ID matches the live `assetlinks.json` or AASA configurations. diff --git a/skills/smartthings-app-to-app-linking-developer/references/best-practice-debugging.md b/skills/smartthings-app-to-app-linking-developer/references/best-practice-debugging.md new file mode 100644 index 0000000..a09c9b4 --- /dev/null +++ b/skills/smartthings-app-to-app-linking-developer/references/best-practice-debugging.md @@ -0,0 +1,39 @@ +# Troubleshooting and Security Best Practices + +Troubleshooting references, security requirements, and diagnostics commands for App-to-App Account Linking. + +--- + +## 🛠️ 1. Troubleshooting Reference + +For dynamic troubleshooting tips and edge-case handling, refer to the [Official App-to-App Documentation](https://developer.smartthings.com/docs/devices/cloud-connected/app-to-app-linking). + +| Symptom | Common Cause | Resolution | +| :--- | :--- | :--- | +| **Falls back to browser** | App not installed, or OS-level domain validation failed. | - Inspect `assetlinks.json` or AASA file hosting and CORS.
- Ensure signing keystore matches registrations. | +| **SmartThings redirection fails** | 1. Skipped URL-decoding.
2. Hardcoded redirect URI. | - Decode `redirect_uri` using UTF-8 before appending parameters.
- Build redirect targets dynamically. | +| **"State Token Mismatch"** | `state` token was modified or skipped. | - Store and return the exact `state` token received from the incoming intent. | +| **Works in US, fails in EU/AP** | Hardcoded `redirect_uri` domain host. | - Do **not** hardcode callback domains. Parse the `redirect_uri` dynamically. | + +--- + +## 🔒 2. Security Requirements + +1. **Client ID Validation**: Always validate the incoming `client_id` parameter against your integration's expected Client ID. Abort linking immediately if they mismatch. +2. **HTTPS Only**: Ensure all redirection URIs and endpoints run exclusively over TLS (HTTPS). +3. **State Token Lifetime**: Treat the `state` parameter as single-use. Do not persist or reuse it across multiple login sessions. + +--- + +## 🔍 3. Diagnostics Commands + +Refer to Google and Apple developer guides for detailed verification diagnostics: + +* **Android (ADB Verification)**: + 1. Check App Link Verification Status: + `adb shell pm get-app-links com.example.yourpartnerapp` *(Status must be `verified`)* + 2. Trigger App Link Manually via ADB: + `adb shell am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://applink.yourdomain.com/smartthings-link?client_id=MY_CLIENT&response_type=code&state=MY_STATE&redirect_uri=https%3A%2F%2Fc2c-us.smartthings.com%2Fc2c-app-to-app-account-linking" com.example.yourpartnerapp` +* **iOS (Universal Links)**: + 1. Inspect console logs and filter by process `swcd` to capture AASA parsing errors. + 2. Toggle **Associated Domains Development** under **Settings > Developer** on your test device to bypass CDN cache. diff --git a/skills/smartthings-cloud-connected-developer/SKILL.md b/skills/smartthings-cloud-connected-developer/SKILL.md index 9512135..251f106 100644 --- a/skills/smartthings-cloud-connected-developer/SKILL.md +++ b/skills/smartthings-cloud-connected-developer/SKILL.md @@ -74,6 +74,8 @@ Write the SmartThings Schema server code (Node.js, etc.) that actually controls Deploy the developed code to a hosting environment (or ngrok), register it in the SmartThings console, and configure OAuth client information. **-> Read the `references/04-hosting-and-registration.md` document and guide the user.** +> **Optional branch (recommended if applicable)**: Once the Schema App is registered in this step, if the developer also has a native Android/iOS app that can authenticate the user, adding **App-to-App Account Linking** (deep-link login instead of browser OAuth) is recommended for the UX/onboarding benefit — implement it via the separate **`smartthings-app-to-app-linking-developer`** skill. This should be done before certification (Step 5) — see the "Optional" section at the end of `references/04-hosting-and-registration.md`. + ### Step 5: Development Testing and Certification Perform Developer Mode device testing and the official certification process based on CbS/STTS. **-> Read the `references/05-certification.md` document and guide the user.** @@ -92,5 +94,8 @@ The agent refers to the following official documentation when verifying concepts | ST-Schema SDK (Node.js) | https://github.com/SmartThingsCommunity/st-schema-nodejs | | SmartThings CLI | https://github.com/SmartThingsCommunity/smartthings-cli | | WWST Certification Requirements | https://developer.smartthings.com/docs/certification/required-capabilities | +| App-to-App Account Linking (optional add-on, separate skill) | https://developer.smartthings.com/docs/devices/cloud-connected/app-to-app-linking | + +> **Related skill**: For optional native-app deep-link login on top of this integration, see the **`smartthings-app-to-app-linking-developer`** skill (requires this Schema App to exist first — see Step 4). Now greet the user, ask if they have information about the device they want to integrate, and begin Step 1. \ No newline at end of file diff --git a/skills/smartthings-cloud-connected-developer/references/04-hosting-and-registration.md b/skills/smartthings-cloud-connected-developer/references/04-hosting-and-registration.md index 41bde9c..4661fc0 100644 --- a/skills/smartthings-cloud-connected-developer/references/04-hosting-and-registration.md +++ b/skills/smartthings-cloud-connected-developer/references/04-hosting-and-registration.md @@ -125,4 +125,18 @@ The issued `ST_CLIENT_ID` and `ST_CLIENT_SECRET` must be injected into the code > **Agent Mandatory Obligation (Local Debugging Support)** > Do not stop at just explaining the code settings. **Be sure to generate and provide a `curl`-based test snippet** so the user can test whether the callback (stateCallback) works correctly in a terminal environment. +--- + +## 5. (Optional) App-to-App Account Linking + +> [!NOTE] +> **Optional, but recommended when applicable.** Once the Schema App is registered above and `ST_CLIENT_ID`/`ST_CLIENT_SECRET` are issued, the developer has everything needed to *optionally* add App-to-App Account Linking — a deep-link based login flow that skips the browser-based OAuth screen when the user already has the developer's native mobile app (Android/iOS) installed. If the developer's own app can already authenticate the user, adding this is recommended: it replaces the browser OAuth handoff with a native-to-native login, which noticeably improves onboarding UX and completion rates. + +Ask the developer: *"Do you also have a native Android or iOS app for this device that can authenticate the user? If so, account linking is recommended — it lets that app skip the browser login screen when it's installed."* + +- **If no, or unsure**: Skip this section and proceed directly to Step 5 (certification/testing) as usual. +- **If yes**: Hand off to the **`smartthings-app-to-app-linking-developer`** skill to implement it now, *before* certification. Note two important constraints so the developer can plan: + 1. App-to-App Linking is configured in the same **Schema Apps** console entry created in Section 2 above — the console path is **Schema Apps tab → select this Schema App → App-to-App Linking (optional) section**. + 2. **Timing matters**: it is much easier to add this now while the Schema App is still uncertified. Once a Schema App is certified/published, it can no longer be edited directly in the console, and enabling App-to-App Linking afterward requires contacting WWST support. See `05-certification.md` for the pre-certification checklist item on this. + Once all the above items are reflected in the code and the server is running, inform the user that they will proceed to Step 5 (05-certification.md) to test whether the integration actually works. \ No newline at end of file diff --git a/skills/smartthings-cloud-connected-developer/references/05-certification.md b/skills/smartthings-cloud-connected-developer/references/05-certification.md index ef1089b..824b33b 100644 --- a/skills/smartthings-cloud-connected-developer/references/05-certification.md +++ b/skills/smartthings-cloud-connected-developer/references/05-certification.md @@ -40,6 +40,7 @@ Before applying for certification in earnest, ask the user whether they have con - [ ] Regional account login: Verify that your own OAuth callback works properly even after changing the Samsung account country (US, EU, AP, etc.) - [ ] Device list and state display confirmed: Devices are displayed normally in the app, and `online/offline` status handling is perfectly applied - [ ] Bidirectional state synchronization: When the device state is changed in your own app, it is immediately reflected in the SmartThings app via `stateCallback` +- [ ] **App-to-App Account Linking decided (Optional, recommended if applicable)**: If the developer has a native Android/iOS app that can authenticate the user (i.e., it can substitute for the browser OAuth login), adding deep-link based account linking is recommended for the UX/onboarding benefit (see `04-hosting-and-registration.md` Section 5 and the `smartthings-app-to-app-linking-developer` skill). If they plan to add it, it must be added **now, before submitting for certification**. Once this Schema App is certified/published, the console entry is locked and enabling App-to-App Linking afterward requires a WWST support request instead of a self-service console change. ## 3. Certification Application and Submission Guide the user to navigate to the **'Certification' tab** on the SmartThings Developer Console's integration project detail page and click the Submit button to proceed with the STTS (SmartThings Test Suite) submission.