@capgo/capacitor-stream-call 0.0.42 → 0.0.50

package/README.md

@@ -6,136 +6,39 @@
   <h2><a href="https://capgo.app/consulting/?ref=plugin"> Fix your annoying bug now, Hire a Capacitor expert 💪</a></h2>
 </div>
 
-Uses the https://getstream.io/ native SDK to implement calling in Capacitor
+A Capacitor plugin that uses the [Stream Video SDK](https://getstream.io/) to enable video calling functionality in your app.
 
-## Install
+## Installation
 
 ```bash
 npm install @capgo/capacitor-stream-call
 npx cap sync
 ```
 
-## Android Setup
+## Configuration
 
-### MainActivity.java
-Modify your `MainActivity.java` to handle incoming calls:
-
-```java
-@Override
-protected void onCreate(Bundle savedInstanceState) {
-  // Save initial intent for StreamCallPlugin (handles killed-state notification)
-  ee.forgr.capacitor.streamcall.StreamCallPlugin.saveInitialIntent(getIntent());
-  
-  super.onCreate(savedInstanceState);
-  
-  // Ensure the activity is visible over the lock screen when launched via full-screen intent
-  if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O_MR1) {
-    setShowWhenLocked(true);
-    setTurnScreenOn(true);
-  } else {
-    getWindow().addFlags(android.view.WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED | android.view.WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON);
-  }
-}
-
-@Override
-protected void onNewIntent(Intent intent) {
-    super.onNewIntent(intent);
-    setIntent(intent);
-    String action = intent.getAction();
-    if ("io.getstream.video.android.action.ACCEPT_CALL".equals(action)) {
-        android.app.KeyguardManager km = (android.app.KeyguardManager) getSystemService(KEYGUARD_SERVICE);
-        if (km != null && km.isKeyguardLocked()) {
-          if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-            km.requestDismissKeyguard(this, new KeyguardManager.KeyguardDismissCallback() {
-                @Override
-                public void onDismissSucceeded() {
-                    forwardAcceptIntent(intent);
-                }
-            });
-          }
-        } else {
-            forwardAcceptIntent(intent);
-        }
-    }
-}
-
-private void forwardAcceptIntent(Intent intent) {
-    ee.forgr.capacitor.streamcall.StreamCallPlugin.saveInitialIntent(intent);
-    PluginHandle pluginHandle = getBridge().getPlugin("StreamCall");
-    if (pluginHandle != null) {
-        com.getcapacitor.Plugin pluginInstance = pluginHandle.getInstance();
-        if (pluginInstance instanceof ee.forgr.capacitor.streamcall.StreamCallPlugin) {
-            ((ee.forgr.capacitor.streamcall.StreamCallPlugin) pluginInstance).handleAcceptCallIntent(intent);
-        }
-    }
-}
-```
-
-### Application Class
-Create or modify your Application class to pre-initialize the plugin:
-
-```java
-@Override
-public void onCreate() {
-    super.onCreate();
-    
-    // Initialize Firebase
-    com.google.firebase.FirebaseApp.initializeApp(this);
-    
-    try {
-        StreamCallPlugin.preLoadInit(this, this);
-    } catch (Exception e) {
-        Log.e("App", "Failed to pre-initialize StreamVideo Plugin", e);
-    }
-}
-```
+### iOS Setup
 
-## Setting up Android StreamVideo apikey
-1. Add your apikey to the Android project:
-```
-your_app/android/app/src/main/res/values/strings.xml
-```
+#### 1. API Key Configuration
+Add your Stream Video API key to `ios/App/App/Info.plist`:
 
-2. Add your apikey to the Android project:
-```xml
-<string name="CAPACITOR_STREAM_VIDEO_APIKEY">your_api_key</string>
-```
-
-## Setting up iOS StreamVideo apikey
-1. Add your apikey to the iOS project:
-```
-your_app/ios/App/App/Info.plist
-```
-
-Add the following to the Info.plist file:
 ```xml
 <dict>
   <key>CAPACITOR_STREAM_VIDEO_APIKEY</key>
-  <string>n8wv8vjmucdw</string>
+  <string>your_api_key_here</string>
   <!-- other keys -->
 </dict>
 ```
 
-## Native Localization
-
-### iOS
+#### 2. Localization (Optional)
+To support multiple languages:
 
-1. Add `Localizable.strings` and `Localizable.stringsdict` files to your Xcode project if you don't have them:
-```
-/App/App/en.lproj/Localizable.strings
-/App/App/en.lproj/Localizable.stringsdict
-```
-
-2. Add new languages to your project in Xcode:
-   - Open project settings
-   - Select your project
-   - Click "Info" tab
-   - Under "Localizations" click "+"
-   - Select the languages you want to add
+1. Add localization files to your Xcode project:
+   - `/App/App/en.lproj/Localizable.strings`
+   - `/App/App/en.lproj/Localizable.stringsdict`
 
-3. Add the translations in your `Localizable.strings`:
-```
-// en.lproj/Localizable.strings
+2. Add translations in `Localizable.strings`:
+```swift
 "stream.video.call.incoming" = "Incoming call from %@";
 "stream.video.call.accept" = "Accept";
 "stream.video.call.reject" = "Reject";
@@ -144,14 +47,13 @@ Add the following to the Info.plist file:
 "stream.video.call.reconnecting" = "Reconnecting...";
 ```
 
-4. Configure the localization provider in your `AppDelegate.swift`:
+3. Configure localization in your `AppDelegate.swift`:
 ```swift
 import StreamVideo
 
 @UIApplicationMain
 class AppDelegate: UIResponder, UIApplicationDelegate {
     func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
-        // Set localization provider to use your app's bundle
         Appearance.localizationProvider = { key, table in
             Bundle.main.localizedString(forKey: key, value: nil, table: table)
         }
@@ -160,12 +62,62 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
 }
 ```
 
-You can find all available localization keys in the [StreamVideo SDK repository](https://github.com/GetStream/stream-video-swift/blob/main/Sources/StreamVideoSwiftUI/Resources/en.lproj/Localizable.strings).
+### Android Setup
+
+#### 1. API Key Configuration
+Add your Stream Video API key to `android/app/src/main/res/values/strings.xml`:
+
+```xml
+<string name="CAPACITOR_STREAM_VIDEO_APIKEY">your_api_key_here</string>
+```
+
+#### 2. MainActivity Configuration
+Modify your `MainActivity.java` to handle incoming calls:
+
+```java
+@Override
+protected void onCreate(Bundle savedInstanceState) {
+  super.onCreate(savedInstanceState);
+  
+  // Enable activity to show over lock screen
+  if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O_MR1) {
+    setShowWhenLocked(true);
+    setTurnScreenOn(true);
+  } else {
+    getWindow().addFlags(android.view.WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED | android.view.WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON);
+  }
+}
+```
+
+#### 3. Application Class Configuration
+Create or modify your Application class to initialize the plugin:
 
-### Android
-1. Create string resources in `/app/src/main/res/values/strings.xml`:
+```java
+import ee.forgr.capacitor.streamcall.StreamCallPlugin;
+
+@Override
+public void onCreate() {
+  super.onCreate();
+  
+  // Initialize Firebase
+  com.google.firebase.FirebaseApp.initializeApp(this);
+  
+  // Pre-initialize StreamCall plugin
+  try {
+    StreamCallPlugin.preLoadInit(this, this);
+  } catch (Exception e) {
+    Log.e("App", "Failed to pre-initialize StreamVideo Plugin", e);
+  }
+}
+```
+
+> **Note:** If you don't have an Application class, you need to create one and reference it in your `AndroidManifest.xml` with `android:name=".YourApplicationClass"`.
+
+#### 4. Localization (Optional)
+Add string resources for different languages:
+
+**Default (`values/strings.xml`):**
 ```xml
-<?xml version="1.0" encoding="utf-8"?>
 <resources>
     <string name="stream_video_call_incoming">Incoming call from %1$s</string>
     <string name="stream_video_call_accept">Accept</string>
@@ -176,9 +128,8 @@ You can find all available localization keys in the [StreamVideo SDK repository]
 </resources>
 ```
 
-2. Add translations for other languages in their respective folders (e.g., `/app/src/main/res/values-fr/strings.xml`):
+**French (`values-fr/strings.xml`):**
 ```xml
-<?xml version="1.0" encoding="utf-8"?>
 <resources>
     <string name="stream_video_call_incoming">Appel entrant de %1$s</string>
     <string name="stream_video_call_accept">Accepter</string>
@@ -189,94 +140,98 @@ You can find all available localization keys in the [StreamVideo SDK repository]
 </resources>
 ```
 
-The SDK will automatically use the system language and these translations.
+## Displaying Caller Information
+
+When receiving incoming calls, you can access caller information including name, user ID, and profile image. This information is automatically extracted from the call data and passed through the event system.
+
+### Getting Caller Information
 
-To receive all on Android from lockscreen you need to listen to specific event `incomingCall`:
+The caller information is available in two ways:
 
-Here is one exemple in angular from our demo app:
+**1. Through Call Events**
 
-```ts
-StreamCall.addListener('incomingCall', async (payload: any) => {
-    console.log('[incomingCall] lock-screen payload', payload);
-    this.incomingCallId = payload.cid;
-    this.isLockscreenIncoming = true;
-    this.cdr.detectChanges();
+The `callEvent` listener provides caller information for incoming calls:
+
+```typescript
+StreamCall.addListener('callEvent', (event) => {
+  if (event.state === 'ringing' && event.caller) {
+    console.log('Incoming call from:', event.caller.name || event.caller.userId);
+    console.log('Caller image:', event.caller.imageURL);
+    // Update your UI to show caller information
+    showIncomingCallUI(event.caller);
+  }
 });
 ```
-This will allow you to display a custom call screen and then enter or reject the call with :
 
-```ts
-  async acceptCall() {
-    if (!this.incomingCallId) return;
-    
-    try {
-      await StreamCall.acceptCall();
-      await this.presentToast('Call accepted', 'success');
-    } catch (error) {
-      console.error('Failed to accept call:', error);
-      await this.presentToast('Failed to accept call', 'danger');
-    }
-  }
+**2. Through Incoming Call Events (Android lock-screen)**
 
-  async rejectCall() {
-    if (!this.incomingCallId) return;
-    
-    try {
-      await StreamCall.rejectCall();
-      this.incomingCallId = null;
-      await this.presentToast('Call rejected', 'success');
-    } catch (error) {
-      console.error('Failed to reject call:', error);
-      await this.presentToast('Failed to reject call', 'danger');
-    }
+The `incomingCall` listener also includes caller information:
+
+```typescript
+StreamCall.addListener('incomingCall', (payload) => {
+  if (payload.caller) {
+    console.log('Lock-screen call from:', payload.caller.name || payload.caller.userId);
+    // Update your lock-screen UI
+    updateLockScreenUI(payload.caller);
   }
+});
 ```
-This is the only way we found to allow the app to use the same UI when phone is lock for the video call.
-This can be done that way only on Android on IOS this part is handle by the OS.
 
+### Caller Information Structure
 
-Also, for Android you need to change your main activity like so:
-```java
-@Override
-protected void onCreate(Bundle savedInstanceState) {
-  // Ensure the activity is visible over the lock screen when launched via full-screen intent
-  if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O_MR1) {
-    setShowWhenLocked(true);
-    setTurnScreenOn(true);
-  } else {
-    getWindow().addFlags(android.view.WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED | android.view.WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON);
-  }
+```typescript
+interface CallMember {
+  userId: string;      // User ID (always present)
+  name?: string;       // Display name (optional)
+  imageURL?: string;   // Profile image URL (optional)
+  role?: string;       // User role (optional)
 }
 ```
 
-Furthermore, you need to edit your Application class like so:
-```java
-import ee.forgr.capacitor.streamcall.StreamCallPlugin;
+### Example Implementation
 
-@Override
-public void onCreate() {
-  super.onCreate();
-  initializeApp();
-}
+Here's how to implement a proper incoming call screen with caller information:
 
-private void initializeApp() {
-  Log.i(TAG, "Initializing application...");
-  // Initialize Firebase
-  com.google.firebase.FirebaseApp.initializeApp(this);
-    try {
-      StreamCallPlugin.preLoadInit(this, this);
-      Log.i(TAG, "StreamVideo Plugin preLoadInit invoked successfully");
-    } catch (Exception e) {
-        Log.e(TAG, "Failed to pre-initialize StreamVideo Plugin", e);
+```typescript
+export class CallService {
+  private callerInfo: CallMember | null = null;
+
+  constructor() {
+    this.setupCallListeners();
+  }
+
+  private setupCallListeners() {
+    StreamCall.addListener('callEvent', (event) => {
+      if (event.state === 'ringing') {
+        this.callerInfo = event.caller || null;
+        this.showIncomingCallScreen();
+      } else if (event.state === 'joined' || event.state === 'left') {
+        this.callerInfo = null;
+        this.hideIncomingCallScreen();
+      }
+    });
+
+    // Android lock-screen support
+    if (Capacitor.getPlatform() === 'android') {
+      StreamCall.addListener('incomingCall', (payload) => {
+        this.callerInfo = payload.caller || null;
+        this.showLockScreenIncomingCall();
+      });
     }
-  Log.i(TAG, "Application initialization completed");
+  }
+
+  private showIncomingCallScreen() {
+    const callerName = this.callerInfo?.name || 'Unknown Caller';
+    const callerImage = this.callerInfo?.imageURL || 'default-avatar.png';
+    
+    // Update your UI components
+    document.getElementById('caller-name').textContent = callerName;
+    document.getElementById('caller-image').src = callerImage;
+    document.getElementById('incoming-call-screen').style.display = 'block';
+  }
 }
 ```
 
-> ⚠️ **WARNING**
-> 
-> You may not have the Application class in your project, if so you need to create it.
-
 ## API
 
 <docgen-index>
@@ -296,6 +251,7 @@ private void initializeApp() {
 * [`getCallStatus()`](#getcallstatus)
 * [`setSpeaker(...)`](#setspeaker)
 * [`switchCamera(...)`](#switchcamera)
+* [`getCallInfo(...)`](#getcallinfo)
 * [Interfaces](#interfaces)
 * [Type Aliases](#type-aliases)
 * [Enums](#enums)
@@ -533,6 +489,23 @@ Switch camera
 --------------------
 
 
+### getCallInfo(...)
+
+```typescript
+getCallInfo(options: { callId: string; }) => Promise<CallEvent>
+```
+
+Get detailed information about an active call including caller details
+
+| Param         | Type                             | Description                      |
+| ------------- | -------------------------------- | -------------------------------- |
+| **`options`** | <code>{ callId: string; }</code> | - Options containing the call ID |
+
+**Returns:** <code>Promise&lt;<a href="#callevent">CallEvent</a>&gt;</code>
+
+--------------------
+
+
 ### Interfaces
 
 
@@ -567,12 +540,14 @@ Switch camera
 
 #### CallEvent
 
-| Prop         | Type                                            | Description                                                    |
-| ------------ | ----------------------------------------------- | -------------------------------------------------------------- |
-| **`callId`** | <code>string</code>                             | ID of the call                                                 |
-| **`state`**  | <code><a href="#callstate">CallState</a></code> | Current state of the call                                      |
-| **`userId`** | <code>string</code>                             | User ID of the participant in the call who triggered the event |
-| **`reason`** | <code>string</code>                             | Reason for the call state change, if applicable                |
+| Prop          | Type                                              | Description                                                    |
+| ------------- | ------------------------------------------------- | -------------------------------------------------------------- |
+| **`callId`**  | <code>string</code>                               | ID of the call                                                 |
+| **`state`**   | <code><a href="#callstate">CallState</a></code>   | Current state of the call                                      |
+| **`userId`**  | <code>string</code>                               | User ID of the participant in the call who triggered the event |
+| **`reason`**  | <code>string</code>                               | Reason for the call state change, if applicable                |
+| **`caller`**  | <code><a href="#callmember">CallMember</a></code> | Information about the caller (for incoming calls)              |
+| **`members`** | <code>CallMember[]</code>                         | List of call members                                           |
 
 
 #### CallState
@@ -766,12 +741,23 @@ The JSON representation for <a href="#listvalue">`ListValue`</a> is JSON array.
 | **`sessionId`** | <code>string</code> | the user sesion_id to pin, if not provided, applies to all sessions |
 
 
+#### CallMember
+
+| Prop           | Type                | Description                   |
+| -------------- | ------------------- | ----------------------------- |
+| **`userId`**   | <code>string</code> | User ID of the member         |
+| **`name`**     | <code>string</code> | Display name of the user      |
+| **`imageURL`** | <code>string</code> | Profile image URL of the user |
+| **`role`**     | <code>string</code> | Role of the user in the call  |
+
+
 #### IncomingCallPayload
 
-| Prop       | Type                    | Description                              |
-| ---------- | ----------------------- | ---------------------------------------- |
-| **`cid`**  | <code>string</code>     | Full call CID (e.g. default:123)         |
-| **`type`** | <code>'incoming'</code> | Event type (currently always "incoming") |
+| Prop         | Type                                              | Description                              |
+| ------------ | ------------------------------------------------- | ---------------------------------------- |
+| **`cid`**    | <code>string</code>                               | Full call CID (e.g. default:123)         |
+| **`type`**   | <code>'incoming'</code>                           | Event type (currently always "incoming") |
+| **`caller`** | <code><a href="#callmember">CallMember</a></code> | Information about the caller             |
 
 
 #### CameraEnabledResponse