Invite Beta Testers to Your SmartThings Schema Integration
SmartThings Developers
Embarking on the journey of software development is exhilarating, but we all know that the path from code to a flawless user experience can be challenging. That's why we've been hard at work building a solution for you to take control of your Cloud Connected Device’s destiny before it launches to millions of SmartThings users around the world.
SmartThings Schema is the quickest method of integrating your Cloud Connected Device with SmartThings. With our new invitations feature, you can share your SmartThings Schema integration to rapidly test and iterate your integration across your environments without needing to publish it to the SmartThings catalog. Once you’re ready to distribute your integration in the SmartThings app, simply submit your integration for Works with SmartThings (WWST) certification using the Certification Console.
Read on to learn more about the process for creating and managing a SmartThings Schema invitation.
Prerequisites
- An existing SmartThings Schema integration: if you haven’t created a SmartThings Schema integration yet, learn how on our developer documentation portal.
- The latest version of the SmartThings Command Line Interface (CLI) installed and signed in using the Samsung account associated with your SmartThings Schema integration.
When running the CLI for the first time, the CLI prompts for access to your Samsung account.
1. Creating Your Invitation
Get started with an interactive session in the SmartThings CLI. The CLI lists all Schema integrations associated with your SmartThings account and walks you through the invitation creation process.
$ smartthings invites:schema:create
The CLI prompts you to select an existing app and asks you to provide the following parameters:
- Description (optional): Your description is displayed to users when viewing the Accept URL
- Accept Limit (optional): Limit the number of installations. If you do not specify a limit, your invitation is limited to a maximum of 500 installs.
After creating your invitation, you will be given an `Accept URL` in the response. Share this URL with your beta testers. Anyone with this URL and a SmartThings account can install your SmartThings Schema integration. Your invitation is valid for 30 days.
Accept URL.2. Sharing Your Invitation
After creating your invitation, you are ready to share your Accept URL and invite others to test your 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 authorize SmartThings to access your Schema integration.
After a user installs your Schema integration, they will be directed to https://my.smartthings.com, and can now use your Schema integration in the SmartThings app. Below, you can see a sample landing page for a Schema invitation.
3. Managing your Invitations
The smartthings invites:schema command displays your invitations, the number of acceptances, and when your invitation will expire.
Accept URL for an invitation with smartthings invites:schema [invitation id]Invitations automatically expire after 30 days. After your invitation expires, new users are not permitted to join your integration with the associated Accept URL. Existing users of your integration are not affected when an invitation expires and may continue to use your integration while it is installed on their SmartThings account. A new invitation can be generated at any time.
As you iterate and continue to develop your Schema integration, existing users of your integration will automatically take advantage of your updated integration — no action is required on either your or your users’ part.
At any time, you can use smartthings invites:schema:delete to close down your invitation. When you delete an invitation or an invitation expires, existing users of your Schema integration will not be affected.
discoveryCallback or stateCallback with the SmartThings Schema globalError.errorEnum: INTEGRATION-DELETED. The globalError can also be provided in a Schema response. For more information, see SmartThings Schema Interaction Types4. Conclusion
The introduction of Invitations for Schema feature is a significant improvement for developers integrating their Cloud Connected Devices. Now you can rapidly test, iterate, and perfect your integration with multiple beta users, all before publishing your device to the SmartThings catalog.
When you’re ready to make your integration available in the SmartThings catalog, it’s time to get Works with SmartThings Certified. Once complete, you can publish your Schema integration in the SmartThings app for use by millions of SmartThings users. Visit https://developer.smartthings.com/docs/certification/overview to learn more about the benefits of Works with SmartThings Certification.
