Skip to main content
DocsSmartThings APIEnterprise API
Docs

Test Your Schema Integration

There are two options for testing your SmartThings Schema integration:

  • Using developer mode in the SmartThings app.

    This option allows for full end-to-end testing, including the customer device onboarding experience. You must create each device (or product) you wish to test in the Certification Console before testing can be conducted. Any members in your organization will be able to onboard and test the registered devices.

  • Inviting others to test your integration through invitations.

    This option allows you to invite other users (including those outside of your organization) to test device functionality without needing to register any devices in the Certification Console. App-to-app linking cannot be tested when using invitations. Additionally, device onboarding is conducted automatically; onboarding flow cannot be tested when using invitations.

Use Developer Mode to Test Your Integration​

  1. Create your device in the Certification Console

    Get started by creating a product in the Certification Console. Your product must be created in the Console before it will appear in the SmartThings app when using developer mode in the next steps.

    tip

    Missing final specs for your product? No problem. Save your product as a draft in the Console to continue with testing your Schema integration. When testing a product in draft form, only the following information is required to be associated with your product in the Console:

    • Product name

    • Model number

    • Schema App

    When creating a product in the Console, click Save as draft to save your product and any product information filled as a draft. Products that are saved as drafts and that are associated with a Schema App will still appear in the SmartThings app My Testing Devices section as described in the next steps.

  2. Enable developer mode in the SmartThings App

    You must enable developer mode in the SmartThings app before your test devices (My Testing Devices) will appear in the app.

  3. Test your device with the SmartThings App

    After you have created your device(s) in the Certification Console and have enabled developer mode in the SmartThings app, you are ready to test your device's interaction with SmartThings. Any member in the same organization that the product is registered under will be able to test your device.

    To test your devices with the SmartThings app:

    1. Launch the SmartThings app. Your SmartThings app and Certification Console must be signed in using the same account.
    2. In the SmartThings app, tap Add device on the Dashboard, or in the Devices tab.
    3. Tap Partner Devices.
    4. Tap My Testing Devices. You can now see and add your self-published devices.

Use Schema Invitations to Invite Others to Test Your Integration​

SmartThings Schema invitations allow you to install your Schema integration without publishing it to the SmartThings catalog, and to invite other users to test your Schema integration. As you iterate and continue to develop your Schema integration, existing users will automatically take advantage of your updated integration - no action is required from either you or your users.

Before getting started, you will need:

  • An existing SmartThings Schema integration.
  • The latest version of the SmartThings CLI installed and signed in using the Samsung account associated with your Schema integration. If you have not previously authorized the CLI to access your SmartThings account, you will be prompted to do so when running the commands listed below.
tip

Check out an example of using the invitations feature in the Samsung developer blog.

Create and Share an Invitation ​​

Get started with an interactive session in the SmartThings CLI. The CLI will list all Schema integrations associated with your SmartThings account and walk you through the invitation creation process:

$ smartthings invites:schema:create

If you already know the ID of your Schema app, you can specify it on the command line (this is particularly helpful if you want to create more than one invitation):

$ smartthings invites:schema:create --schema-app myapp_id

The CLI will prompt you to select an existing app and will ask you to provide the following parameters:

  • Description (optional): your description will be displayed to users when viewing your invitation.
  • Accept Limit (optional): Limit the number of installations. If you do not specify a limit, your invitation will automatically be limited to a maximum of 500 installs.

After following the prompts in the CLI, a new invitation will be created for you: ​

──────────────────────────────────────────────────────────────────────────────────────────────
 Invitation Id    0aa97541-0d89-4ff7-b8d6-3553b07a28b1
 Description      my invitation description
 Expiration       2023-10-31T19:48:55.000Z
 Acceptances      0
 Accept URL       https://invitations.smartthings.com/schemaApp/INVITATION_ID
 Schema App Id    viper_98fdced9-1a7a-48bd-a226-f787d0adc653
 Schema App Name  My ST-Schema App
──────────────────────────────────────────────────────────────────────────────────────────────

​ Send the Accept URL to the users you want to invite to use your SmartThings Schema app. Anyone with this URL and a SmartThings account can install your SmartThings Schema integration.

When a user accesses your Accept URL, they will be directed to a landing page with your Schema integration logo, support email, and description as defined when you originally created your Schema integration. The user will be prompted to select a Location associated with their SmartThings account and to authorize SmartThings to access your Schema integration.

important

Invitations automatically expire after 30 days. After your invitation expires, new users will not be able to join your integration with the associated Accept URL. Your Schema app will continue to function for existing users, but will not allow existing users to reinstall your app. A new invitation can be generated at any time.

Check the Status of an Invitation​

View your existing invitations:

smartthings invites:schema

If you know your invitation ID, you can specify this directly to view the accept URL link, number of acceptances, and more:

$ smartthings invites:schema 0aa97541-0d89-4ff7-b8d6-3553b07a28b1
─────────────────────────────
 Invitation Id    0aa97541-0d89-4ff7-b8d6-3553b07a28b1
 Description      my invitation description
 Expiration       2023-10-31T19:48:55.000Z
 Acceptances      0
 Accept URL       https://invitations.smartthings.com/schemaApp/INVITATION_ID
 Schema App Id    viper_98fdced9-1a7a-48bd-a226-f787d0adc653
 Schema App Name  My ST-Schema App  
─────────────────────────────

Delete an Invitation​

Deleting an invitation will nullify the Accept URL, preventing new users from installing your Schema app. Existing users will be unable to reinstall your Schema app or change the installed app location.

caution

Existing installations of your shared Schema app will not be affected. To prevent existing users from continuing to use your Schema app, send a proactive discoveryCallback or stateCallback with the SmartThings Schema globalError.errorEnum: INTEGRATION-DELETED. The globalError can also be provided in a Schema response.

To delete an invitation:

smartthings invites:schema:delete

and select a previously created invitation. If you know your invitation ID, you can specify this directly: ​

$ smartthings invites:schema:delete 0aa97541-0d89-4ff7-b8d6-3553b07a28b1
Invitation 0aa97541-0d89-4ff7-b8d6-3553b07a28b1 revocation requested. (This may take a few moments to complete.)