Device Sharing

Purpose

Device managers can share a device with others (known as the receivers). The receivers can use the device after accepting the share invitation.

The main features include:

• Device managers can share a device or group and query or remove receivers.
• Receivers can accept device share invitations and query or remove sharers.

Access

source 'https://github.com/tuya/tuya-pod-specs.git'
platform :ios, '11.0'

target 'Your_Project_Name' do
    pod "ThingSmartBusinessExtensionKit"
end

Models

• Sharing results

  open class ThingDeviceShareResult : NSObject {
  
      /// The relationship ID.
      open var memberId: Int
  
      /// The nickname.
      open var nickName: String
  
      /// The username that is the phone number or email address.
      open var userName: String
  }
  

• Sharing information

  open class ThingDeviceShareInfo : NSObject {
  
      open var content: String
  
      open var code: String
  
      open var shortUrl: String
  }
  

• Sharing methods

  public enum ThingDeviceShareType : Int {
      case account = 0
      case QQ = 1
      case wechat = 2
      case message = 3
      case email = 4
      case copy = 5
      case more = 6
      case contact = 7
  }
  

• Share code information

  open class ThingDeviceShareCodeInfo : NSObject {
  
      open var appId: String
  
      /// Device/Group ID
      open var resId: String
  
      /// Resource type: 1 Device type, 2 Group type
      open var resType: Int32
  
      /// Device/Group icon
      open var resIcon: String
  
      /// Device/Group name
      open var resName: String
  
      /// Name of the sharer
      open var nickName: String
  
      /// Sharing channels
      open var shareSource: ThingDeviceShareType
  
      /// Group ID of the sharer
      open var groupId: Int64
  }
  

• Sharer information

  open class ThingDeviceSharer : NSObject {
  
      /// The relationship ID.
      open var memberId: Int
  
      /// The nickname.
      open var nickName: String
  
      /// The username that is the phone number or email address.
      open var userName: String
  }
  
  

• Sharer details

  open class ThingDeviceSharerDetail : NSObject {
  
      /// The shared devices
      open var devices: [ThingSmartShareDeviceModel]
  
      /// The account information, email, or phone number.
      open var mobile: String
  
      /// The user nickname.
      open var name: String
  
      /// The remarks.
      open var remarkName: String
  }
  

• Sharing management

  open class ThingDeviceShareManager : NSObject {
      //...
  }
  

APIs related to sharers

Determine whether the device or group supports sharing

Request parameter	Type	Description
resId	String	The ID of the resource (device or group) to be shared.
resType	ThingShareResType	The resource type. Valid values: ThingShareResTypeDevice: The type is device. ThingShareResTypeGroup: The type is group.
success	(Bool) -> Void	The success callback.
failure	(Error) -> Void	The failure callback.

    /// Determine whether the device or group supports sharing
    /// - Parameters:
    ///   - resId: The ID of the device or group to be shared
    ///   - resType: ThingShareResTypeDevice if a device is shared, otherwise ThingShareResTypeGroup
    ///   - success: Success callback, true if sharing is supported, otherwise false.
    ///   - failure: Failure callback
    open class func supportShare(_ resId: String, resType:ThingShareResType, success: @escaping (Bool) -> Void, failure: @escaping (Error) -> Void)

Query the remaining share times of the device or group

Request parameter	Type	Description
resId	String	The ID of the resource (device or group) to be shared.
resType	ThingShareResType	The resource type. Valid values: ThingShareResTypeDevice: The type is device. ThingShareResTypeGroup: The type is group.
success	(Int32) -> Void	The success callback.
failure	(Error) -> Void	The failure callback.

    /// Get the remaining share times of the device or group.
    /// For now, group does not support this feature. In short, it can only be used to check the remaining share times of the device.
    /// - Parameters:
    ///   - resId: The ID of the device or group to be shared
    ///   - resType: ThingShareResTypeDevice if a device is shared, otherwise ThingShareResTypeGroup
    ///   - success: Success callback. Unlimited if times is -1
    ///   - failure: Failure callback
    open class func remainingShareTimes(_ resId: String, resType:ThingShareResType, success: @escaping (Int32) -> Void, failure: @escaping (Error) -> Void)

Share a device or group with another user

Share a group with users without adding them to the recently shared contact list.

Request parameter	Type	Description
resId	String	The ID of the resource (device or group) to be shared.
resType	ThingShareResType	The resource type. Valid values: ThingShareResTypeDevice: The type is device. ThingShareResTypeGroup: The type is group.
spaceId	Int64	The home ID of the device or group.
userAccount	String	The user ID.
success	(ThingDeviceShareResult) -> Void	The success callback.
failure	(Error) -> Void	The failure callback.

    /// Share a device or group to another user
    /// - Parameters:
    ///   - resId: The ID of the device or group to be shared
    ///   - resType: ThingShareResTypeDevice if a device is shared, otherwise ThingShareResTypeGroup
    ///   - spaceId: The home ID of the device or group
    ///   - userAccount: the account of the user shared to
    ///   - success: Success callback with the sharing result
    ///   - failure: Failure callback
    open class func share(_ resId: String, resType: ThingShareResType, spaceId: Int64, userAccount: String, success: @escaping (ThingDeviceShareResult) -> Void, failure: @escaping (Error) -> Void)

Remove the receiver

Request parameter	Type	Description
memberId	Int	The member ID of the receiver.
resId	String	The ID of the resource (device or group) to be shared.
resType	ThingShareResType	The resource type. Valid values: ThingShareResTypeDevice: The type is device. ThingShareResTypeGroup: The type is group.
success	() -> Void	The success callback.
failure	(Error) -> Void	The failure callback.

    /// Remove the receiver of device or group
    /// - Parameters:
    ///   - memberId: The ID of the member to be removed
    ///   - resId: The ID of device or group to be shared
    ///   - resType: ThingShareResTypeDevice if a device is shared, otherwise ThingShareResTypeGroup
    ///   - success: Success callback
    ///   - failure: Failure callback
    open class func removeReceiver(_ memberId: Int, resId: String, resType: ThingShareResType, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

Query the receivers with shared access to a device or group

Request parameter	Type	Description
resId	String	The ID of the resource (device or group) to be shared.
resType	ThingShareResType	The resource type. Valid values: ThingShareResTypeDevice: The type is device. ThingShareResTypeGroup: The type is group.
page	Int32	The page number, which starts from 1. This parameter is invalid for groups because all group members are returned at a time.
pageSize	Int32	The page size. This parameter is invalid for groups because all group members are returned at a time.
success	([ThingSmartShareMemberModel]) -> Void	The success callback.
failure	(Error) -> Void	The failure callback.

    /// Get receivers of a device or group shared to
    /// - Parameters:
    ///   - resId: The ID of device or group to be shared
    ///   - resType: ThingShareResTypeDevice if a device is shared, otherwise ThingShareResTypeGroup
    ///   - page: The number of page to fetch, starting from 1. This parameter is useful only for devices. For groups, it will return all members at once.
    ///   - pageSize: The size of page to fetch, which must be greater than zero. This parameter is useful only for device. For groups, it will return all members at once.
    ///   - success: Success callback with a list of ThingSmartShareMemberModel
    ///   - failure: Failure callback
    open class func receivers(_ resId: String, resType: ThingShareResType, page: Int32, pageSize: Int32, success: @escaping ([ThingSmartShareMemberModel]?) -> Void, failure: @escaping (Error) -> Void)

Update the expiration time of the sharing

Note that you cannot update the expiration time of the sharing for groups.

Request parameter	Type	Description
memberId	Int	The member ID of the receiver.
resId	String	The ID of the resource (device or group) to be shared.
resType	ThingShareResType	The resource type. Valid values: ThingShareResTypeDevice: The type is device. ThingShareResTypeGroup: The type is group.
mode	ThingShareValidationType	The expiration mode.
endTime	Int64	The expiration time, in milliseconds. This parameter takes effect only for the mode ThingShareValidationTypePeriod.
success	() -> Void	The success callback.
failure	(Error) -> Void	The failure callback.

    /// Update the sharing expiration date
    /// - Parameters:
    ///   - memberId: The ID of a member to be updated
    ///   - resId: The ID of the device or group to be shared
    ///   - resType: ThingShareResTypeDevice if a device is shared, otherwise ThingShareResTypeGroup
    ///   - mode: ThingShareValidationTypeForever if the sharing is valid forever, otherwise ThingShareValidationTypePeriod
    ///   - endTime: Timestamp in milliseconds if mode is ThingShareValidationTypePeriod, or it will be ignored.
    ///   - success: Success callback
    ///   - failure: Failure callback
    open class func updateShareExpirationDate(_ memberId: Int, resId: String, resType: ThingShareResType, mode: ThingShareValidationType, endTime: Int64, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

Query recently shared contacts

Request parameter	Type	Description
success	([ThingSmartShareMemberModel]) -> Void	The success callback.
failure	(Error) -> Void	The failure callback.

    /// Get members who were recently shared
    /// - Parameters:
    ///   - success: Success callback with a list of ThingSmartShareMemberModel
    ///   - failure: Failure callback
    open class func relationMembers(_ success: @escaping ([ThingSmartShareMemberModel]?) -> Void, failure: @escaping (Error) -> Void)

Remove a member from the list of recently shared contacts

Request parameter	Type	Description
uid	String	The ID of the member to be removed.
success	() -> Void	The success callback.
failure	(Error) -> Void	The failure callback.

    /// Remove members who were recently shared
    /// - Parameters:
    ///   - uid: The ID of a member to be removed
    ///   - success: Success callback
    ///   - failure: Failure callback
    open class func removeRelationMember(_ uid: String, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

Generate a share code

Generate a share code to share a device with a third party. You cannot share groups through share codes.

Request parameter	Type	Description
resId	String	The ID of the resource (device or group) to be shared.
resType	ThingShareResType	The resource type. Valid values: ThingShareResTypeDevice: The type is device. ThingShareResTypeGroup: The type is group.
spaceId	Int64	The home ID of the device.
shareType	ThingDeviceShareType	The channel for sending the share code.
shareCount	Int32	The number of times a device is shared through the share code.
success	(ThingDeviceShareInfo) -> Void	The success callback.
failure	(Error) -> Void	The failure callback.

    /// Create a share code to share a device
    /// For now, group does not support this feature. In short, it can only be used to share a device.
    /// - Parameters:
    ///   - resId: The ID of the device or group to be shared
    ///   - resType: ThingShareResTypeDevice if a device is shared, otherwise ThingShareResTypeGroup
    ///   - spaceId: The home ID of the device or group
    ///   - shareType: The type to share the code, ie: email, message, etc. For more information, see ThingDeviceShareType
    ///   - shareCount: The count of valid uses for the share code
    ///   - success: Success callback
    ///   - failure: Failure callback
    open class func createShareInfo(_ resId: String, resType:ThingShareResType, spaceId: Int64, shareType: ThingDeviceShareType, shareCount: Int32, success: @escaping (ThingDeviceShareInfo) -> Void, failure: @escaping (Error) -> Void)

Configure a universal link and scheme for your app to use share codes.

View the channel code on the Tuya Developer Platform.

You can implement the following method in AppDelegate to show share invitations to users: optional func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool.

    func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
        //weburl  https://appScheme.applink.smart321.com/share?link=appScheme://share_link?code=MN54PUQQ
        guard let webUrl = userActivity.webpageURL else { return false }
       let params = ["activityType": NSUserActivityTypeBrowsingWeb, "webUrl": webUrl.absoluteString]
        let components = NSURLComponents(string: webUrl.absoluteString)
        guard let items = components?.queryItems else {return false}
        let item = items.first {$0.name == "link"}

        guard let link = item?.value?.removingPercentEncoding else {return false}
        let linkComponents = URLComponents(string: link)
        guard let linkItems = linkComponents?.queryItems, let host = linkComponents?.host else {return false}

        if (host == "share_link") {
            let codeItem = linkItems.first {$0.name == "code"}
            if codeItem == nil {return false}

            //show share invate to user
            ...
            return true
        }

        // other logic...
    }

APIs related to receivers

Validate a share code

Request parameter	Type	Description
code	String	The share code.
success	(Bool) -> Void	The success callback.
failure	(Error) -> Void	The failure callback.

    /// Validate a share code
    /// - Parameters:
    ///   - code: The share code
    ///   - success: Success callback, true if valid
    ///   - failure: Failure callback
    open class func validate(_ code: String, success: @escaping (Bool) -> Void, failure: @escaping (Error) -> Void)

Query information of a share code

Request parameter	Type	Description
code	String	The share code.
success	(ThingDeviceShareCodeInfo) -> Void	The success callback.
failure	(Error) -> Void	The failure callback.

    /// Get info of the share code
    /// - Parameters:
    ///   - code: The share code
    ///   - success: Success callback, with ThingDeviceShareCodeInfo
    ///   - failure: Failure callback
    open class func shareCodeInfo(_ code: String, success: @escaping (ThingDeviceShareCodeInfo) -> Void, failure: @escaping (Error) -> Void)

Accept a share invitation

Request parameter	Type	Description
code	String	The share code.
success	() -> Void	The success callback.
failure	(Error) -> Void	The failure callback.

    /// Accept the share invitation
    /// - Parameters:
    ///   - code: The share code
    ///   - success: Success callback
    ///   - failure: Failure callback
    open class func accept(_ code: String, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

Remove a shared device or group

Request parameter	Type	Description
resId	String	The ID of the resource (device or group) to be shared.
resType	ThingShareResType	The resource type. Valid values: ThingShareResTypeDevice: The type is device. ThingShareResTypeGroup: The type is group.
success	() -> Void	The success callback.
failure	(Error) -> Void	The failure callback.

    /// Remove a share of device or group
    /// - Parameters:
    ///   - resId: The ID of the device or group to be shared
    ///   - resType: ThingShareResTypeDevice if a device is shared, otherwise ThingShareResTypeGroup
    ///   - success: Success callback
    ///   - failure: Failure callback
    open class func removeShare(_ resId: String, resType: ThingShareResType, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

Query the sharers of the device or group

Request parameter	Type	Description
success	() -> Void	The success callback.
failure	(Error) -> Void	The failure callback.

    /// Get the sharers who share the device or group
    /// - Parameters:
    ///   - success: Success callback, with a list of ThingDeviceSharer
    ///   - failure: Failure callback
    open class func sharers(_ success: @escaping ([ThingDeviceSharer]?) -> Void, failure: @escaping (Error) -> Void)

Query the name of the sharer

Request parameter	Type	Description
resId	String	The ID of the resource (device or group) to be shared.
resType	ThingShareResType	The resource type. Valid values: ThingShareResTypeDevice: The type is device. ThingShareResTypeGroup: The type is group.
success	(String) -> Void	The success callback.
failure	(Error) -> Void	The failure callback.

    /// Get the name of the sharer
    /// - Parameters:
    ///   - resId: The ID of the device or group to be shared
    ///   - resType: ThingShareResTypeDevice if a device is shared, otherwise ThingShareResTypeGroup
    ///   - success: Success callback
    ///   - failure: Failure callback
    open class func sharerName(_ resId: String, resType: ThingShareResType, success: @escaping (String) -> Void, failure: @escaping (Error) -> Void)

Query the details of the sharer

Request parameter	Type	Description
memberId	Int	The member ID of the sharer.
success	(ThingDeviceSharerDetail) -> Void	The success callback.
failure	(Error) -> Void	The failure callback.

    /// Get the detail of sharer who shares the device or group
    /// - Parameters:
    ///   - memberId: The ID of sharer who shares the device or group
    ///   - success: Success callback, with ThingDeviceSharerDetail
    ///   - failure: Failure callback
    open class func sharerDetail(_ memberId: Int, success: @escaping (ThingDeviceSharerDetail) -> Void, failure: @escaping (Error) -> Void)

Remove a sharer

Request parameter	Type	Description
memberId	Int	The member ID of the sharer.
success	() -> Void	The success callback.
failure	(Error) -> Void	The failure callback.

    /// Remove the sharer
    /// - Parameters:
    ///   - memberId: The ID of the sharer to be removed
    ///   - success: Success callback
    ///   - failure: Failure callback
    open class func removeSharer(_ memberId: Int, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

Update the name of a sharer

Request parameter	Type	Description
memberId	Int	The member ID of the sharer.
name	String	The name of the sharer.
success	() -> Void	The success callback.
failure	(Error) -> Void	The failure callback.

    /// Update the name of the sharer
    /// - Parameters:
    ///   - memberId: The ID of sharer to be updated
    ///   - name: The new name of the sharer
    ///   - success: Success callback
    ///   - failure: Failure callback
    open class func updateSharer(_ memberId: Int, name: String, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

For more information, refer to the demo.