Bring call duration into the calling native SDKs

Author: garchiro7

articles/communication-services/how-tos/calling-sdk/call-duration.md

@@ -0,0 +1,57 @@
+---
+title: Manage the call duration events using Calling SDKs
+titleSuffix: An Azure Communication Services how-to guide
+description: Use Azure Communication Services Calling SDKs to handle call duration events
+
+ms.author: jorgegarc
+ms.service: azure-communication-services
+ms.subservice: calling
+ms.topic: how-to 
+ms.date: 09/01/2024
+ms.custom: template-how-to
+zone_pivot_groups: acs-plat-ios-android-windows
+---
+
+# Manage call duration
+
+## Start Time
+
+The ability to use **call start time events** allows developers to capture and utilize the exact time a call is initiated. By subscribing to these events, developers gain valuable insights that can be applied in various use cases, such as performance tracking and user experience enhancements, among other uses.
+
+### Use Cases
+
+#### Enhanced User Experience
+Developers can use the call start time to display call duration to users in real time, improving the user experience by providing transparency on how long the user has been in the call.
+
+**Example:** In a video conferencing app, the UI can display an active call timer showing how long the participants have been in the meeting, increasing user engagement.
+
+By utilizing the call start time API events, developers can build more robust, feature-rich applications that improve the user experience, ensure compliance, and support detailed performance monitoring.
+
+#### Performance and Monitoring Analytics
+By retrieving the call start time, developers can measure call duration and integrate with monitoring systems to analyze the performance of calls. This information is crucial for identifying call quality issues, optimizing network performance, and understanding user behavior.
+
+**Example:** A customer support center can track how long agents stay on calls and identify trends related to call durations, improving resource management.
+
+## Prerequisites
+
+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F)
+- A deployed Communication Services resource. [Create a Communication Services resource](../../quickstarts/create-communication-resource.md)
+- A user access token to enable the calling client. For more information, see [Create and manage access tokens](../../quickstarts/identity/access-tokens.md).
+- Optional: Complete the quickstart to [add voice calling to your application](../../quickstarts/voice-video-calling/getting-started-with-calling.md)
+
+::: zone pivot="platform-android"
+[!INCLUDE [Manage Call duration events using Android](./includes/call-duration/android.md)]
+::: zone-end
+
+::: zone pivot="platform-ios"
+[!INCLUDE [Manage Call duration events using iOS](./includes/call-duration/ios.md)]
+::: zone-end
+
+::: zone pivot="platform-windows"
+[!INCLUDE [Manage Call duration events using Windows](./includes/call-duration/windows.md)]
+::: zone-end
+
+## Next steps
+
+- [Learn how to manage calls](./manage-calls.md)
+- [Learn about the UI Library](../../concepts/ui-library/ui-library-overview.md)

articles/communication-services/how-tos/calling-sdk/includes/call-duration/android.md

@@ -0,0 +1,30 @@
+---
+author: iaulakh
+ms.service: azure-communication-services
+ms.topic: include
+ms.date: 09/01/2024
+ms.author: iaulakh
+---
+[!INCLUDE [Install SDK](../install-sdk/install-sdk-android.md)]
+
+## Get call start time 
+To retrieve the call start time, subscribe to the `addOnStartTimeUpdatedListener` on the `CommonCall` object. The start time is returned as a `Date` object, indicating when the call was bootstrapped.
+
+``` java
+CommonCall call;
+PropertyChangedListener onStartTimeUpdated = this::OnStartTimeUpdated;
+
+// subscribe to start time updated
+call.addOnStartTimeUpdatedListener(onStartTimeUpdated);
+
+// get start time
+private void OnStartTimeUpdated(PropertyChangedEvent propertyChangedEvent) {
+    SimpleDateFormat dateFormatter = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
+    dateFormatter.setTimeZone(TimeZone.getDefault());
+    String dateString = dateFormatter.format(call.getStartTime());
+    // dateString with dateFormatter
+}
+
+// unsubscribe to start time updated
+call.removeOnStartTimeUpdatedListener(onStartTimeUpdated);
+```

articles/communication-services/how-tos/calling-sdk/includes/call-duration/ios.md

@@ -0,0 +1,28 @@
+---
+author: iaulakh
+ms.service: azure-communication-services
+ms.topic: include
+ms.date: 09/01/2024
+ms.author: iaulakh
+---
+[!INCLUDE [Install SDK](../install-sdk/install-sdk-ios.md)]
+
+## Get call start time 
+To retrieve the call start time, set the `didUpdateStartTime` on the `CallDelegate`. The start time is returned as a `Date` object, indicating when the indicating when the call was bootstrapped.
+
+``` swift
+class CallObserver : NSObject, CallDelegate
+{
+    // subscribe to didUpdateStartTime
+    public func call(_ call: Call, didUpdateStartTime args: PropertyChangedEventArgs) {
+        let dateFormatter = DateFormatter()
+        dateFormatter.dateFormat = "yyyy-MM-dd HH:mm:ss"
+        dateFormatter.timeZone = TimeZone.current
+        let dateString = dateFormatter.string(from: call.startTime)
+        print("==> didUpdateStartTime for call: \(dateString)")
+    }
+}
+
+// set call delegate
+call.delegate = CallObserver()
+```

articles/communication-services/how-tos/calling-sdk/includes/call-duration/windows.md

@@ -0,0 +1,26 @@
+---
+author: iaulakh
+ms.service: azure-communication-services
+ms.topic: include
+ms.date: 09/01/2024
+ms.author: iaulakh
+---
+[!INCLUDE [Install SDK](../install-sdk/install-sdk-windows.md)]
+
+## Get call start time  
+To retrieve the call start time, subscribe to the `StartTimeUpdated` on the `CommonCommunicationCall` object. The start time is returned as a `DateTimeOffset` object, indicating when the call was bootstrapped.
+
+``` cs
+CommonCommunicationCall call;
+
+// subscribe to start time updated
+call.StartTimeUpdated += Call_OnStartTimeUpdated;
+
+private async void Call_OnStartTimeUpdated(object sender, PropertyChangedEventArgs args)
+{
+    // call.StartTime
+}
+
+// unsubscribe to start time updated
+call.StartTimeUpdated -= Call_OnStartTimeUpdated;
+```

articles/communication-services/toc.yml

@@ -336,6 +336,8 @@ items:
         href: how-tos/cte-calling-sdk/manage-calls.md
       - name: Manage Teams meeting Lobby
         href: how-tos/calling-sdk/lobby.md
+      - name: Manage call duration
+        href: how-tos/calling-sdk/call-duration.md
       - name: PowerPoint Live
         href: how-tos/calling-sdk/powerpoint-live.md
       - name: Record calls