Video Doorbell

Last Updated on : 2024-06-17 03:35:06download

A doorbell can be bound with a home and stay online on your app. In this case, if the doorbell is pressed, IPC SDK receives a doorbell call event. Doorbell call operations are implemented with the management class. For example, listen for changes in the doorbell call status, and answer, hang up, or reject calls.

To implement video streaming during doorbell calls, the live streaming API methods must also be integrated.

Get doorbell call management class

Example

Objective-C:

ThingSmartDoorBellManager *manager = [ThingSmartDoorBellManager sharedInstance];

Swift:

let manager = ThingSmartDoorBellManager.sharedInstance()

Doorbell call models

Doorbell calls are encapsulated by the model class ThingSmartDoorBellCallModel. This class is used to store information about doorbell calls and maintain the doorbell call status. Each doorbell ring event has its own ThingSmartDoorBellCallModel model, identified by a unique messageId.

Parameter Description
type The type of doorbell call. Valid values:
  • doorbell
  • ac_doorbell
  • Custom type
devId The device ID.
messageId The unique identifier of the doorbell call message.
time The Unix timestamp when the doorbell call is triggered, in seconds.
answeredBySelf Indicates whether the device owner has answered the doorbell call.
answeredByOther Indicates whether another member has answered the doorbell call.
canceled Indicates whether the doorbell call was canceled.

Get doorbell call models

To get the status of a doorbell call, use the model ThingSmartDoorBellCallModel to return the target instance of ThingSmartDoorBellCallModel.

API description

- (ThingSmartDoorBellCallModel *)callModelWithMessageId:(NSString *)messageId;

Parameters

Parameter Description
messageId The unique identifier of the doorbell call message.

Register doorbell call listener

The app process must be active before the listener can work as expected. If the app process runs in the background or is terminated, the listener will not work.

API description

- (void)addObserver:(id<ThingSmartDoorBellObserver>)observer;

Parameters

Parameter Description
ThingSmartDoorBellObserver The doorbell call listener.

ThingSmartDoorBellObserver

The doorbell call listener involves the callbacks throughout the life cycle of doorbell calls. The following table describes these callbacks.

API name Parameter list Return value Description
didReceivedFromDevice ThingSmartDoorBellCallModel, ThingSmartDeviceModel void The doorbell call event from the device is received.
doorBellCallDidHangUp ThingSmartDoorBellCallModel void The doorbell call was hung up on the device.
doorBellCallDidAnsweredByOther ThingSmartDoorBellCallModel void Another member has answered the doorbell call. The service layer determines whether to automatically cancel or hold the call.
  • To decline the call, call refuseDoorBellCall to end the call.
  • To hold the call, the device owner can pick up and listen to the ongoing call that is being answered by another member but cannot talk through the call.
    doorBellCallDidAnswered ThingSmartDoorBellCallModel void The doorbell call was answered.
    doorBellCallDidCanceled ThingSmartDoorBellCallModel, BOOL void The doorbell call was canceled. The parameter isTimeOut indicates whether the call is automatically canceled due to timeout or manually canceled on the device.
    doorBellCallDidRefuse ThingSmartDoorBellCallModel void The doorbell call was declined.

    When the doorbell call event didReceivedFromDevice from the device is received, we recommend that you save the object ThingSmartDoorBellCallModel or the doorbell call identifier messageId. Either will be required in the API request to answer, hang up, or decline a call.

    Example

    Objective-C:

    @interface CameraDoorbellManager ()<ThingSmartDoorBellObserver>
    @property (nonatomic, copy) NSString *messageId;
    @end
    
    @implementation CameraDoorbellManager
    
    - (void)doorBellCall:(ThingSmartDoorBellCallModel *)callModel didReceivedFromDevice:(ThingSmartDeviceModel *)deviceModel {
        self.messageId = callModel.messageId;
    }
    
    - (void)doorBellCallDidRefuse:(ThingSmartDoorBellCallModel *)callModel {
    
    }
    
    - (void)doorBellCallDidHangUp:(ThingSmartDoorBellCallModel *)callModel {
    
    }
    
    - (void)doorBellCallDidAnsweredByOther:(ThingSmartDoorBellCallModel *)callModel {
    
    }
    
    - (void)doorBellCallDidAnswered:(ThingSmartDoorBellCallModel *)callModel {
    
    }
    
    - (void)doorBellCallDidCanceled:(ThingSmartDoorBellCallModel *)callModel timeOut:(BOOL)isTimeOut {
    
    }
    
    @end
    

    Swift:

    class DoorbellManager: NSObject {
        let manager = ThingSmartDoorBellManager.sharedInstance()
        var messageId:String = ""
    }
    
    extension DoorbellManager:ThingSmartDoorBellObserver {
        func doorBellCall(_ callModel: ThingSmartDoorBellCallModel!, didReceivedFromDevice deviceModel: ThingSmartDeviceModel!) {
            messageId = callModel.messageId
        }
    
        func doorBellCallDidRefuse(_ callModel: ThingSmartDoorBellCallModel!) {
    
        }
    
        func doorBellCallDidHangUp(_ callModel: ThingSmartDoorBellCallModel!) {
    
        }
    
        func doorBellCallDidAnswered(byOther callModel: ThingSmartDoorBellCallModel!) {
    
        }
    
        func doorBellCallDidCanceled(_ callModel: ThingSmartDoorBellCallModel!, timeOut isTimeOut: Bool) {
    
        }
    }
    

    Remove doorbell call listener

    Remove a doorbell call listener if it is not required.

    API description

    - (void)removeObserver:(id<ThingSmartDoorBellObserver>)observer;
    

    Example

    Objective-C:

    [[ThingSmartDoorBellManager sharedInstance] removeObserver:self];
    

    Swift:

    ThingSmartDoorBellManager.sharedInstance()?.remove(self)
    

    Ignore subsequent calls from a specific doorbell

    Specify whether to automatically ignore subsequent calls from a specific doorbell when users are already on a call from another doorbell.

    Property description

    @property (nonatomic, assign) BOOL ignoreWhenCalling;
    
    Property Description
    ignoreWhenCalling
    • YES: Ignore
    • NO: Not ignore
    Default value: YES.

    Set timeout for all doorbell calls

    Set the timeout for doorbell calls. If a doorbell call is not answered within the specified period, the callback doorBellCallDidCanceled will be invoked to send a notification and end the call.

    Property description

    @property (nonatomic, assign) NSInteger doorbellRingTimeOut;
    
    Property Description
    doorbellRingTimeOut The timeout for doorbell calls, in seconds, defaulting to 25.

    Set timeout for a specific doorbell call

    Set the timeout for doorbell calls by device ID. If a doorbell call is not answered within the specified period, the callback doorBellCallDidCanceled will be invoked to send a notification and end the call.

    Property description

    @property (nonatomic, weak) id<ThingSmartDoorBellConfigDataSource> doorBellConfigDataSource;
    

    Parameters

    Parameter Description
    ThingSmartDoorBellConfigDataSource The data source for the doorbell settings.

    ThingSmartDoorBellConfigDataSource

    The data source for the doorbell settings is shown below.

    API name Parameter list Return value Description
    doorbellRingTimeOut NSInteger, NSString * NSInteger Set the timeout for doorbell calls by device ID.

    Answer doorbell call

    Answer a doorbell call when it rings. The call may fail if it was answered, canceled, or for other reasons. In case of failure, the reason is returned as an error message. For more information, see Error codes.

    API description

    - (ThingDoorBellError)answerDoorBellCall:(NSString *)messageId;
    

    Example

    Objective-C:

    [[ThingSmartDoorBellManager sharedInstance] answerDoorBellCall:self.messageId];
    

    Swift:

    ThingSmartDoorBellManager.sharedInstance()?.answerDoorBellCall(messageId)
    

    Decline doorbell call

    Decline a doorbell call when it rings.

    API description

    - (void)refuseDoorBellCall:(NSString *)messageId;
    

    Example

    Objective-C:

    [[ThingSmartDoorBellManager sharedInstance] refuseDoorBellCall:self.messageId];
    

    Swift:

    ThingSmartDoorBellManager.sharedInstance()?.refuseDoorBellCall(messageId)
    

    Hang up doorbell call

    Hang up a doorbell call after it is received. The call might fail to be hung up if it goes unanswered or for other reasons. In case of failure, the reason is returned as an error message. For more information, see Error codes.

    API description

    - (ThingDoorBellError)hangupDoorBellCall:(NSString *)messageId;
    

    Example

    Objective-C:

    [[ThingSmartDoorBellManager sharedInstance] hangupDoorBellCall:self.messageId];
    

    Swift:

    ThingSmartDoorBellManager.sharedInstance()?.hangupDoorBellCall(messageId)
    

    Process doorbell calls sent from other sources

    Handle the doorbell call received via push notification instead of MQTT. Generate a doorbell call model based on the passed parameters to implement operations such as answering, hanging up, or declining the call.

    API description

    - (void)generateCall:(NSDictionary *)params;
    

    Parameters

    Parameter Description
    params The call message data. See Demo for the push message details.

    Description of key-value pairs in params

    key value
    devId The device ID.
    cid The nodeId of the device.
    edata The message ID.
    eType The type of the received call message.
    time The timestamp of the received call message.

    Example

    For more information, see Demo.

    Error code

    For more information, see SDK Error Codes.

    Enum value Error code Description
    ThingDoorBellError_NoError 0 The operation is successful without errors.
    ThingDoorBellError_CallFailed -2300 Failed to process the call. Possible reason:
    • The call event ended. For example, it was hung up or declined.
    • Same reason as that of ThingDoorBellError_NotSupport.
    ThingDoorBellError_AnsweredByOther -2301 The doorbell call is being answered by another user.
    ThingDoorBellError_DidCanceled -2302 The doorbell call was canceled on the device.
    ThingDoorBellError_TimeOut -2303 The doorbell call timed out.
    ThingDoorBellError_AnsweredBySelf -2304 The doorbell call was answered.
    ThingDoorBellError_NotAnswered -2305 The doorbell call was hung up, without being answered.
    ThingDoorBellError_NotSupport -2306 The device type such as doorbell is not supported.

    Doorbell audio resource file

    To implement the features of the low-power doorbell, you must download the default resource file resources.zip, decompress it, and then add the resources to your project. You can also add a custom audio file with the default file name.