feat: make push notification listeners more flexible for easier debugging (#1542)

- [x] Removed notification listeners inside the SDK, but export them as
utility functions
- [x] Documentation guides how to add own listeners using the utility
functions. This fixes #1447
- [x] Dogfood apps are updated
- [x] Added doc on how to add incoming/outgoing call UIs on app root
level
- [x] throw error when deprecated navigation functions for ringing calls
are used
- [x] add section about how to add sound to ringing calls on foreground
- [ ] make a 1.3 release

Author: santhoshvai

packages/react-native-sdk/docusaurus/docs/reactnative/04-ui-components/call/ringing-call-content.mdx

@@ -49,15 +49,21 @@ To use the `RingingCallContent` you can do the following:
 
 ```tsx {11}
 import {
+  StreamCall,
   useCalls,
   RingingCallContent,
 } from '@stream-io/video-react-native-sdk';
 
 const Call = () => {
-  const calls = useCalls();
+  // filter for ringing calls
+  const calls = useCalls().filter(
+    (c) => c.state.callingState === CallingState.RINGING,
+  );
+  const call = calls[0];
+  if (!call) return null;
 
   return (
-    <StreamCall call={call[0]}>
+    <StreamCall call={call}>
       <RingingCallContent />
     </StreamCall>
   );

packages/react-native-sdk/docusaurus/docs/reactnative/06-advanced/03-ringing.mdx

@@ -44,50 +44,65 @@ The caller will automatically join the call once the first callee accepts the ca
 The call will automatically stop if every callee rejects the call.
 
 :::note
-When ring is true, a push notification will be sent to the members, provided their app have the required setup.
+When ring is true, a **push notification** will be sent to the members, provided their app have the required setup.
 For more details around push notifications, please check [this page](../../advanced/push-notifications/overview).
 :::
 
 ## Watch for incoming and outgoing calls
 
-The easiest way to watch for incoming and outgoing calls is to use the `useCalls` hook.
+The easiest way to watch for incoming and outgoing calls is to use the `useCalls` hook and the [`RingingCallContent`](../../ui-components/call/ringing-call-content) component.
 
-```tsx
-import { useCalls, CallingState } from '@stream-io/video-react-native-sdk';
+**Important**: Make sure that the ringing calls are watched in the root component of your app. This makes sure that in whichever screen the user is in, or if the app was opened from a push notification it is shown. Below is an example of how to watch for ringing calls in the root component of your App.
 
-export const MyCallUI = () => {
-  const calls = useCalls();
+```ts
+import { SafeAreaView, StyleSheet } from 'react-native';
+import {
+  StreamCall,
+  StreamVideo,
+  useCalls,
+  RingingCallContent,
+  StreamVideoClient,
+  User,
+} from '@stream-io/video-react-native-sdk';
 
-  // handle incoming ring calls
-  const incomingCalls = calls.filter(
-    (call) =>
-      call.isCreatedByMe === false &&
-      call.state.callingState === CallingState.RINGING,
+const user: User = {
+  id: 'sara',
+};
+const apiKey = '<STREAM-API-KEY>';
+const tokenProvider = () => Promise.resolve('<USER-TOKEN>');
+const client = StreamVideoClient.getOrCreateInstance({ apiKey, tokenProvider, user });
+
+const RingingCalls = () => {
+  // filter for ringing calls
+  const calls = useCalls().filter(
+    (c) => c.state.callingState === CallingState.RINGING,
   );
-
-  const [incomingCall] = incomingCalls;
-  if (incomingCall) {
-    // render the incoming call UI
-    return <MyIncomingCallUI call={incomingCall} />;
-  }
-
-  // handle outgoing ring calls
-  const outgoingCalls = calls.filter(
-    (call) =>
-      call.isCreatedByMe === true &&
-      call.state.callingState === CallingState.RINGING,
+  const call = calls[0];
+  if (!call) return null;
+
+  return (
+    <StreamCall call={call}>
+      <SafeAreaView style={StyleSheet.absoluteFill}>
+        <RingingCallContent />
+      </SafeAreaView>
+    </StreamCall>
+  );
+}
+
+const App = () => {
+  return (
+    <StreamVideo client={client}>
+      <MyApp />
+      <RingingCalls />
+    <StreamVideo>
   );
-
-  const [outgoingCall] = outgoingCalls;
-  if (outgoingCall) {
-    // render the outgoing call UI
-    return <MyOutgoingCallUI call={outgoingCall} />;
-  }
-
-  return null;
 };
+
+export default App;
 ```
 
+In the above example, the component `RingingCalls` renders over the rest of the App whenever there is a incoming or outgoing call. Alternatively you can use a Modal view or Dialog to show there is a ringing call over the rest of your app.
+
 ## Canceling a call
 
 A caller can cancel an outgoing call until the first callee accepts the call. Canceling a call will stop the signaling flow.