{"id":18695338,"url":"https://github.com/smartthingscommunity/api-app-subscription-example-js","last_synced_at":"2025-04-12T07:25:13.087Z","repository":{"id":42963674,"uuid":"215081079","full_name":"SmartThingsCommunity/api-app-subscription-example-js","owner":"SmartThingsCommunity","description":"Example API Access SmartApp that shows the state and allows control of devices","archived":false,"fork":false,"pushed_at":"2024-09-03T15:53:59.000Z","size":1809,"stargazers_count":12,"open_issues_count":3,"forks_count":11,"subscribers_count":70,"default_branch":"master","last_synced_at":"2025-03-26T02:42:37.104Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SmartThingsCommunity.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-10-14T15:36:23.000Z","updated_at":"2025-03-01T22:05:34.000Z","dependencies_parsed_at":"2023-01-28T14:01:46.373Z","dependency_job_id":null,"html_url":"https://github.com/SmartThingsCommunity/api-app-subscription-example-js","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartThingsCommunity%2Fapi-app-subscription-example-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartThingsCommunity%2Fapi-app-subscription-example-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartThingsCommunity%2Fapi-app-subscription-example-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SmartThingsCommunity%2Fapi-app-subscription-example-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SmartThingsCommunity","download_url":"https://codeload.github.com/SmartThingsCommunity/api-app-subscription-example-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248532181,"owners_count":21119871,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T11:14:40.614Z","updated_at":"2025-04-12T07:25:13.067Z","avatar_url":"https://github.com/SmartThingsCommunity.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Event Subscription API App Example\n\n## Overview\n\nThis NodeJS Express application illustrates how to create an _API Access_ SmartApp that connects to your SmartThings\naccount with OAuth2 to control devices and subscribe to device events. The application uses the \n[SmartThings SmartApp](https://www.npmjs.com/package/@smartthings/smartapp) SDK NPM module for making the\nAPI calls to control switch devices and subscribe to switch events. The app creates a web page that displays\nthe state of all switches in a location and allows those switches to be turned on and off.\n\nAPI access tokens and web session state are stored local files. This storage mechanism is not suitable for\nproduction use. There are alternative storage mechanisms for DynamoDB and Firebase.\n\n## Files and directories \n\n- public\n  - images -- image assets used by the web pages\n  - javascript -- javascript used by the web page for rendering and controlling devices\n  - stylesheets -- stylesheets used by the web pages\n- views\n  - devices.ejs -- page that displays switch devices and allows them to be controlled\n  - error.ejs -- error page\n  - index.ejs -- initial page with link to connect to SmartThings\n- server.js -- the Express server and SmartApp\n- .env -- file you create with app credentials\n- package.json -- The Node.js package file\n\n## Getting Started\n\n### Prerequisites\n- A [SmartThings](https://smartthings.com) account with at least one location and device with the switch capability\n- The [SmartThings CLI](https://github.com/SmartThingsCommunity/smartthings-cli#readme) installed\n- [Node.js](https://nodejs.org/en/) and [npm](https://www.npmjs.com/) installed\n- [ngrok](https://ngrok.com/) or similar tool to create a secure tunnel to a publicly available URL\n\nNote that as an alternative to running the app locally you can use [Glitch](glitch.com) to host your app.\n\n## Instructions\n\n### 1. Set up your server\n\n#### If running locally and tunneling using ngrok or similar tool\nClone [this GitHub repository](https://github.com/SmartThingsCommunity/api-app-subscription-example-js), cd into the\ndirectory, and install the Node modules with NPM:\n```\ngit clone https://github.com/SmartThingsCommunity/api-app-subscription-example-js.git\ncd api-app-subscription-example-js\nnpm install\n```\n\nStart ngrok or similar tool to create a secure tunnel to your local server. Note that the free version of ngrok will\nchange the subdomain part of the URL every time you restart it, so you will need to update the server URL in the `.env`. \nAlternately, you can use the paid version which supports reserved subdomains:\n```\nngrok http 3000\n```\n\nCreate a file named `.env` in the project directory and set the base URL of the server to your ngrok URL,\nFor example:\n```\nSERVER_URL=https://315e5367357f.ngrok.app\n```\n\nStart your server and make note of the information it prints out:\n```\nnode server.js\n```\n\n#### If using Glitch\n\nRemix this Glitch project: [midnight-cloudy-sceptre](https://glitch.com/edit/#!/midnight-cloudy-sceptre) and wait for\nthe server to start.\n\n### 2. Register your SmartThings app\n\nLook at the log output of your local server or Glitch app. You should see something like this:\n```\nTarget URL -- Copy this value into the targetUrl field of you app creation request:\nhttps://315e5367357f.ngrok.app\n\nRedirect URI -- Copy this value into redirectUris field of your app creation request:\nhttps://315e5367357f.ngrok.app/oauth/callback\n\nWebsite URL -- Visit this URL in your browser to log into SmartThings and connect your account:\nhttps://315e5367357f.ngrok.app\n```\n\nRun the `smartthings apps:create` command to create a new app. You will be prompted for the required\ninformation. The following is an example of the output from the command:\n\n```bash\n~ % smartthings apps:create\n? What kind of app do you want to create? (Currently, only OAuth-In apps are supported.) OAuth-In App\n\nMore information on writing SmartApps can be found at\n  https://developer.smartthings.com/docs/connected-services/smartapp-basics\n\n? Display Name My API Subscription App\n? Description Allows control of SmartThings devices\n? Icon Image URL (optional) \n? Target URL (optional) https://315e5367357f.ngrok.app\n\nMore information on OAuth 2 Scopes can be found at:\n  https://www.oauth.com/oauth2-servers/scope/\n\nTo determine which scopes you need for the application, see documentation for the individual endpoints you will use in your app:\n  https://developer.smartthings.com/docs/api/public/\n\n? Select Scopes. r:devices:*, x:devices:*, r:locations:*\n? Add or edit Redirect URIs. Add Redirect URI.\n? Redirect URI (? for help) https://315e5367357f.ngrok.app/oauth/callback\n? Add or edit Redirect URIs. Finish editing Redirect URIs.\n? Choose an action. Finish and create OAuth-In SmartApp.\nBasic App Data:\n─────────────────────────────────────────────────────────────────────────────\n Display Name     My API Subscription App                                    \n App Id           3275eef3-xxxx-xxxx-xxxx-xxxxxxxxxxxx                       \n App Name         amyapisubscriptionapp-aaea18b1-xxxx-xxxx-xxxx-xxxxxxxxxxxx \n Description      Allows control of SmartThings devices                      \n Single Instance  true                                                       \n Classifications  CONNECTED_SERVICE                                          \n App Type         API_ONLY                                                   \n Target URL       https://315e5367357f.ngrok.app                             \n Target Status    PENDING                                                    \n─────────────────────────────────────────────────────────────────────────────\n\n\nOAuth Info (you will not be able to see the OAuth info again so please save it now!):\n───────────────────────────────────────────────────────────\n OAuth Client Id      7a850484-xxxx-xxxx-xxxx-xxxxxxxxxxxx \n OAuth Client Secret  3581f317-xxxx-xxxx-xxxx-xxxxxxxxxxxx \n───────────────────────────────────────────────────────────\n```\n\nSave the output of the create command for later use. It contains the client ID and secret of your app. You\nwon't be able to see those values again.\n\nAfter running the create command look at your server logs for a line similar to this one:\n```\n2024-09-03T14:24:14.967Z warn: Unexpected CONFIRMATION request for app 3275eef3-c18c-4c0c-bbe6-1fbd36739b5c, \nreceived {\"messageType\":\"CONFIRMATION\",\"confirmationData\":{\"appId\":\"3275eef3-c18c-4c0c-bbe6-1fbd36739b5c\",\n\"confirmationUrl\":\"https://api.smartthings.com/apps/3275eef3-xxxx-xxxx-xxxx-xxxxxxxxxxxx/confirm-registration?token=53c980fa-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"}}\n```\n\nPaste the URL into a browser or request it with a utility like curl to enable callbacks to your app. \nThe response should contain the\n_targetURL_ value from your app creation request, for example:\n```\n{\n    targetUrl: \"https://315e5367357f.ngrok.app\"\n}\n```\n\n### 3. Update and restart your server\n\nAdd the _APP_ID_, _CLIENT_ID_ and _CLIENT_SECRET_ properties from `apps:create` command \nresponse to your `.env` file:\n```\nAPP_ID=3275eef3-xxxx-xxxx-xxxx-xxxxxxxxxxxx\nCLIENT_ID=7a850484-xxxx-xxxx-xxxx-xxxxxxxxxxxx\nCLIENT_SECRET=3581f317-xxxx-xxxx-xxxx-xxxxxxxxxxxx\n```\n\nRestart your server:\n```\nnode server.js\n```\n\nNote that if you are using Glitch your server will restart automatically when you edit the `.env` file.\n\n### 4. Log into SmartThings\n\nOpen the Website URL from the server log (`https://315e5367357f.ngrok.app` in this example) in a browser, \nlog in with your SmartThings account credentials, and \nchoose a location. You should see a page listing all devices in that location with the _switch_\ncapability. Tapping the device on the page should turn the switch on and off. You should also see\nthe states of the switches on the page change when you turn them on and off with the SmartThings\nmobile app.\n\n## Troubleshooting\n\nYour app should be able to control switches and receive events from them. If the app UI is not being updated\nwhen you change the switch state with the SmartThings mobile app, make sure that the target status is `CONFIRMED` \nby running the following command:\n```\n~ % smartthings apps 3275eef3-xxxx-xxxx-xxxx-xxxxxxxxxxxx\n─────────────────────────────────────────────────────────────────────────────\n Display Name     My API Subscription App                                    \n App Id           3275eef3-xxxx-xxxx-xxxx-xxxxxxxxxxxx                       \n App Name         amyapisubscriptionapp-ab9fb550-xxxx-xxxx-xxxx-xxxxxxxxxxxx \n Description      Allows SmartThings switches to be controlled               \n Single Instance  true                                                       \n Classifications  CONNECTED_SERVICE                                          \n App Type         API_ONLY                                                   \n Target URL       https://315e5367357f.ngrok.app                             \n Target Status    CONFIRMED                                                  \n─────────────────────────────────────────────────────────────────────────────\n```\n\nIf the target status is 'PENDING' you need to confirm the registration by running the following command and \nvisiting the confirmation URL in a browser or using a utility like curl:\n```\nsmatthings apps:register 3275eef3-xxxx-xxxx-xxxx-xxxxxxxxxxxx\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartthingscommunity%2Fapi-app-subscription-example-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmartthingscommunity%2Fapi-app-subscription-example-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartthingscommunity%2Fapi-app-subscription-example-js/lists"}