react-native-acoustic-connect-beta 18.0.13 → 18.0.15

package/src/docs/NativeImplementation.md

@@ -0,0 +1,176 @@
+# Native Implementation for Dialog Event Tracking
+
+This document summarizes the native implementation of the dialog event tracking functionality for both Android and iOS platforms.
+
+## Overview
+
+The dialog event tracking system has been implemented across all three layers:
+1. **TypeScript Interface** (`src/specs/react-native-acoustic-connect.nitro.ts`)
+2. **Android Implementation** (`android/src/main/java/com/acousticconnectrn/HybridAcousticConnectRN.kt`)
+3. **iOS Implementation** (`ios/HybridAcousticConnectRN.swift`)
+
+## Interface Methods Added
+
+Four new methods were added to the `AcousticConnectRN` interface:
+
+### 1. `logDialogShowEvent`
+- **Purpose**: Logs when a dialog is shown
+- **Parameters**: 
+  - `dialogId`: Unique identifier for the dialog
+  - `dialogTitle`: The title of the dialog
+  - `dialogType`: The type of dialog (alert, custom, modal)
+- **Returns**: `Boolean` indicating success/failure
+
+### 2. `logDialogDismissEvent`
+- **Purpose**: Logs when a dialog is dismissed
+- **Parameters**:
+  - `dialogId`: Unique identifier for the dialog
+  - `dismissReason`: The reason for dismissing the dialog
+- **Returns**: `Boolean` indicating success/failure
+
+### 3. `logDialogButtonClickEvent`
+- **Purpose**: Logs when a button in a dialog is clicked
+- **Parameters**:
+  - `dialogId`: Unique identifier for the dialog
+  - `buttonText`: The text of the clicked button
+  - `buttonIndex`: The index of the clicked button
+- **Returns**: `Boolean` indicating success/failure
+
+### 4. `logDialogCustomEvent`
+- **Purpose**: Logs custom dialog events with additional data
+- **Parameters**:
+  - `dialogId`: Unique identifier for the dialog
+  - `eventName`: The name of the custom event
+  - `values`: A map of values associated with the event
+- **Returns**: `Boolean` indicating success/failure
+
+## Android Implementation
+
+### File: `android/src/main/java/com/acousticconnectrn/HybridAcousticConnectRN.kt`
+
+All four methods have been implemented using the existing `Connect.logCustomEvent()` API:
+
+```kotlin
+override fun logDialogShowEvent(dialogId: String, dialogTitle: String, dialogType: String): Boolean {
+    var result = false
+    try {
+        val values = HashMap<String?, String?>()
+        values["dialogId"] = dialogId
+        values["dialogTitle"] = dialogTitle
+        values["dialogType"] = dialogType
+        values["eventType"] = "dialog_show"
+        values["timestamp"] = System.currentTimeMillis().toString()
+        
+        result = Connect.logCustomEvent("DialogShowEvent", values, EOMonitoringLevel.kEOMonitoringLevelInfo.value)
+    } catch (e: Exception) {
+        println("Error logging dialog show event: ${e.message}")
+        result = false
+    }
+    return result
+}
+```
+
+### Key Features:
+- **Error Handling**: All methods include try-catch blocks for robust error handling
+- **Consistent Logging**: Uses the same `Connect.logCustomEvent()` API as other events
+- **Timestamp**: Includes millisecond timestamps for event tracking
+- **Event Type**: Each event includes an `eventType` field for easy filtering
+- **Monitoring Level**: Uses `EOMonitoringLevel.kEOMonitoringLevelInfo.value` for consistent logging level
+
+## iOS Implementation
+
+### File: `ios/HybridAcousticConnectRN.swift`
+
+All four methods have been implemented using the existing `ConnectCustomEvent().logEvent()` API:
+
+```swift
+func logDialogShowEvent(dialogId: String, dialogTitle: String, dialogType: String) throws -> Bool {
+    let values: [String: Any] = [
+        "dialogId": dialogId,
+        "dialogTitle": dialogTitle,
+        "dialogType": dialogType,
+        "eventType": "dialog_show",
+        "timestamp": String(Int(Date().timeIntervalSince1970 * 1000))
+    ]
+    
+    let result = ConnectCustomEvent().logEvent("DialogShowEvent", values: values, level: kConnectMonitoringLevelType.connectMonitoringLevelInfo)
+    return result
+}
+```
+
+### Key Features:
+- **Error Handling**: Uses Swift's throwing mechanism for error handling
+- **Consistent Logging**: Uses the same `ConnectCustomEvent().logEvent()` API as other events
+- **Timestamp**: Includes millisecond timestamps for event tracking
+- **Event Type**: Each event includes an `eventType` field for easy filtering
+- **Monitoring Level**: Uses `kConnectMonitoringLevelType.connectMonitoringLevelInfo` for consistent logging level
+- **Type Safety**: Leverages Swift's strong typing for parameter validation
+
+## Generated Spec Files
+
+The Nitro framework automatically generated the interface specifications:
+
+### Android: `nitrogen/generated/android/kotlin/com/margelo/nitro/acousticconnectrn/HybridAcousticConnectRNSpec.kt`
+- Contains abstract method declarations for all four dialog event methods
+- Properly annotated with `@DoNotStrip` and `@Keep` for ProGuard compatibility
+
+### iOS: `nitrogen/generated/ios/swift/HybridAcousticConnectRNSpec.swift`
+- Contains protocol method declarations for all four dialog event methods
+- Includes proper Swift documentation comments
+
+## Data Structure
+
+All dialog events include consistent metadata:
+
+```json
+{
+  "dialogId": "unique_dialog_identifier",
+  "eventType": "dialog_show|dialog_dismiss|dialog_button_click|dialog_custom_event",
+  "timestamp": "1703123456789",
+  // Additional fields specific to each event type
+}
+```
+
+## Error Handling Strategy
+
+### Android:
+- Uses try-catch blocks to prevent app crashes
+- Logs error messages to console for debugging
+- Returns `false` on any exception
+
+### iOS:
+- Uses Swift's throwing mechanism
+- Errors are propagated up the call stack
+- Caller can handle errors appropriately
+
+## Performance Considerations
+
+- **Lightweight**: All methods are lightweight and don't perform heavy operations
+- **Async Safe**: Methods can be called from any thread
+- **Memory Efficient**: Uses simple data structures and minimal memory allocation
+- **Network Efficient**: Events are batched and sent according to existing Connect SDK policies
+
+## Testing
+
+The implementation can be tested using:
+
+1. **Unit Tests**: Test individual method calls
+2. **Integration Tests**: Test with actual dialog components
+3. **End-to-End Tests**: Verify events appear in Acoustic Connect dashboard
+
+## Future Enhancements
+
+Potential improvements for future versions:
+
+1. **Event Batching**: Batch multiple dialog events for better performance
+2. **Custom Event Types**: Allow developers to define custom dialog event types
+3. **Event Filtering**: Add configuration options to filter specific dialog events
+4. **Analytics Integration**: Direct integration with analytics platforms
+5. **Performance Metrics**: Track dialog performance metrics (show time, interaction time)
+
+## Compatibility
+
+- **Backward Compatible**: No breaking changes to existing functionality
+- **Platform Agnostic**: Consistent API across Android and iOS
+- **Framework Compatible**: Works with existing Connect SDK infrastructure
+- **Version Safe**: Compatible with current React Native versions 

package/src/examples/DialogTrackingExample.tsx

@@ -0,0 +1,163 @@
+/********************************************************************************************
+* Copyright (C) 2025 Acoustic, L.P. All rights reserved.
+*
+* NOTICE: This file contains material that is confidential and proprietary to
+* Acoustic, L.P. and/or other developers. No license is granted under any intellectual or
+* industrial property rights of Acoustic, L.P. except as may be provided in an agreement with
+* Acoustic, L.P. Any unauthorized copying or distribution of content from this file is
+* prohibited.
+********************************************************************************************/
+
+import React, { useState } from 'react';
+import { View, Text, Button, Alert, StyleSheet } from 'react-native';
+import { useDialogTracking } from '../utils/useDialogTracking';
+
+/**
+ * Example component demonstrating dialog event tracking
+ * Shows how to use both automatic Alert.alert interception and manual custom dialog tracking
+ */
+const DialogTrackingExample: React.FC = () => {
+    const [customDialogVisible, setCustomDialogVisible] = useState(false);
+    const { 
+        generateDialogId, 
+        trackDialogShow, 
+        trackDialogDismiss, 
+        createTrackedButton 
+    } = useDialogTracking();
+
+    // Example 1: Automatic Alert.alert tracking (no additional code needed)
+    const showAlertDialog = () => {
+        Alert.alert(
+            'Confirmation',
+            'Are you sure you want to proceed?',
+            [
+                { text: 'Cancel', style: 'cancel' },
+                { text: 'OK', onPress: () => console.log('OK pressed') }
+            ]
+        );
+    };
+
+    // Example 2: Manual custom dialog tracking
+    const showCustomDialog = () => {
+        const dialogId = generateDialogId();
+        const title = 'Custom Dialog';
+        const buttons = [
+            { text: 'Cancel', style: 'cancel' as const },
+            { text: 'Confirm', onPress: () => console.log('Confirm pressed') }
+        ];
+
+        // Track dialog show event
+        trackDialogShow(dialogId, title, buttons);
+        setCustomDialogVisible(true);
+    };
+
+    const hideCustomDialog = () => {
+        const dialogId = generateDialogId(); // In real app, you'd store this
+        trackDialogDismiss(dialogId, 'user_dismiss');
+        setCustomDialogVisible(false);
+    };
+
+    // Example 3: Custom dialog with tracked buttons
+    const showTrackedCustomDialog = () => {
+        const dialogId = generateDialogId();
+        const title = 'Tracked Custom Dialog';
+        const originalButtons = [
+            { text: 'No', style: 'cancel' as const },
+            { text: 'Yes', onPress: () => console.log('Yes pressed') }
+        ];
+
+        // Create tracked buttons
+        const trackedButtons = originalButtons.map((button, index) => 
+            createTrackedButton(dialogId, button, index)
+        );
+
+        trackDialogShow(dialogId, title, trackedButtons);
+        setCustomDialogVisible(true);
+    };
+
+    return (
+        <View style={styles.container}>
+            <Text style={styles.title}>Dialog Tracking Examples</Text>
+            
+            <View style={styles.buttonContainer}>
+                <Button 
+                    title="Show Alert Dialog (Auto-tracked)" 
+                    onPress={showAlertDialog} 
+                />
+            </View>
+
+            <View style={styles.buttonContainer}>
+                <Button 
+                    title="Show Custom Dialog (Manual tracking)" 
+                    onPress={showCustomDialog} 
+                />
+            </View>
+
+            <View style={styles.buttonContainer}>
+                <Button 
+                    title="Show Tracked Custom Dialog" 
+                    onPress={showTrackedCustomDialog} 
+                />
+            </View>
+
+            {customDialogVisible && (
+                <View style={styles.customDialog}>
+                    <Text style={styles.dialogTitle}>Custom Dialog</Text>
+                    <Text style={styles.dialogMessage}>
+                        This is a custom dialog with manual tracking
+                    </Text>
+                    <View style={styles.dialogButtons}>
+                        <Button title="Cancel" onPress={hideCustomDialog} />
+                        <Button title="OK" onPress={hideCustomDialog} />
+                    </View>
+                </View>
+            )}
+        </View>
+    );
+};
+
+const styles = StyleSheet.create({
+    container: {
+        flex: 1,
+        padding: 20,
+        justifyContent: 'center',
+    },
+    title: {
+        fontSize: 24,
+        fontWeight: 'bold',
+        textAlign: 'center',
+        marginBottom: 30,
+    },
+    buttonContainer: {
+        marginVertical: 10,
+    },
+    customDialog: {
+        position: 'absolute',
+        top: '50%',
+        left: 20,
+        right: 20,
+        backgroundColor: 'white',
+        borderRadius: 10,
+        padding: 20,
+        elevation: 5,
+        shadowColor: '#000',
+        shadowOffset: { width: 0, height: 2 },
+        shadowOpacity: 0.25,
+        shadowRadius: 3.84,
+    },
+    dialogTitle: {
+        fontSize: 18,
+        fontWeight: 'bold',
+        marginBottom: 10,
+    },
+    dialogMessage: {
+        fontSize: 16,
+        marginBottom: 20,
+    },
+    dialogButtons: {
+        flexDirection: 'row',
+        justifyContent: 'space-around',
+    },
+});
+
+export default DialogTrackingExample; 

package/src/examples/HOCDialogExample.tsx

@@ -0,0 +1,253 @@
+/********************************************************************************************
+* Copyright (C) 2025 Acoustic, L.P. All rights reserved.
+*
+* NOTICE: This file contains material that is confidential and proprietary to
+* Acoustic, L.P. and/or other developers. No license is granted under any intellectual or
+* industrial property rights of Acoustic, L.P. except as may be provided in an agreement with
+* Acoustic, L.P. Any unauthorized copying or distribution of content from this file is
+* prohibited.
+********************************************************************************************/
+
+import * as React from 'react';
+import { View, Text, TouchableOpacity, StyleSheet, Alert } from 'react-native';
+import Connect from '../components/Connect';
+
+/**
+ * Example demonstrating HOC-based Paper Dialog tracking
+ * 
+ * This approach requires minimal code changes:
+ * 1. Create tracked versions of your dialog components
+ * 2. Use the tracked versions instead of the original ones
+ * 3. All dialog events are automatically tracked!
+ */
+const HOCDialogExample: React.FC = () => {
+  const [dialogVisible, setDialogVisible] = React.useState(false);
+
+  // Example 1: React Native Alert.alert (automatically tracked)
+  const showAlertDialog = () => {
+    Alert.alert(
+      'Confirmation Alert',
+      'This is a native alert dialog that is automatically tracked.',
+      [
+        { text: 'Cancel', style: 'cancel' },
+        { text: 'OK', onPress: () => console.log('Alert OK pressed') }
+      ]
+    );
+  };
+
+  // Example 2: Paper Dialog with HOC tracking
+  const showPaperDialog = () => {
+    setDialogVisible(true);
+  };
+
+  const hidePaperDialog = () => {
+    setDialogVisible(false);
+  };
+
+  return (
+    <Connect captureDialogEvents={true} captureKeyboardEvents={false}>
+      <View style={styles.container}>
+        <Text style={styles.title}>HOC Dialog Tracking Example</Text>
+        <Text style={styles.subtitle}>
+          Minimal code changes required - just wrap your dialog components!
+        </Text>
+
+        <View style={styles.buttonContainer}>
+          <TouchableOpacity style={styles.button} onPress={showAlertDialog}>
+            <Text style={styles.buttonText}>Show Alert.alert</Text>
+            <Text style={styles.buttonSubtext}>Automatically tracked</Text>
+          </TouchableOpacity>
+
+          <TouchableOpacity style={styles.button} onPress={showPaperDialog}>
+            <Text style={styles.buttonText}>Show Paper Dialog (HOC)</Text>
+            <Text style={styles.buttonSubtext}>Minimal code changes</Text>
+          </TouchableOpacity>
+        </View>
+
+        <View style={styles.infoContainer}>
+          <Text style={styles.infoTitle}>How to use HOC approach:</Text>
+          <Text style={styles.infoText}>1. Create tracked dialog components</Text>
+          <Text style={styles.infoText}>2. Use tracked versions instead of originals</Text>
+          <Text style={styles.infoText}>3. All events automatically tracked!</Text>
+          <Text style={styles.infoText}>4. No manual tracking code needed</Text>
+        </View>
+
+        <View style={styles.codeContainer}>
+          <Text style={styles.codeTitle}>Example Setup Code:</Text>
+          <Text style={styles.codeText}>
+            {`// In your app setup
+import { withAcousticAutoDialog } from 'react-native-acoustic-connect-beta';
+import { Dialog, Portal } from 'react-native-paper';
+
+// Create tracked versions
+const TrackedDialog = withAcousticAutoDialog(Dialog);
+const TrackedPortal = withAcousticAutoDialog(Portal);
+
+// Use TrackedDialog instead of Dialog - that's it!`}
+          </Text>
+        </View>
+
+        {/* Example of how the tracked dialog would be used */}
+        {dialogVisible && (
+          <View style={styles.exampleDialog}>
+            <Text style={styles.dialogTitle}>Example Dialog</Text>
+            <Text style={styles.dialogContent}>
+              This shows how you would use the tracked dialog components.
+              In a real app, you would use TrackedDialog instead of Dialog.
+            </Text>
+            <View style={styles.dialogActions}>
+              <TouchableOpacity style={styles.dialogButton} onPress={hidePaperDialog}>
+                <Text style={styles.dialogButtonText}>Cancel</Text>
+              </TouchableOpacity>
+              <TouchableOpacity 
+                style={[styles.dialogButton, styles.primaryButton]} 
+                onPress={() => {
+                  console.log('Dialog confirmed!');
+                  hidePaperDialog();
+                }}
+              >
+                <Text style={styles.dialogButtonText}>Confirm</Text>
+              </TouchableOpacity>
+            </View>
+          </View>
+        )}
+      </View>
+    </Connect>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    padding: 20,
+    backgroundColor: '#f5f5f5',
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: 'bold',
+    textAlign: 'center',
+    marginBottom: 10,
+    color: '#333',
+  },
+  subtitle: {
+    fontSize: 16,
+    textAlign: 'center',
+    marginBottom: 30,
+    color: '#666',
+    fontStyle: 'italic',
+  },
+  buttonContainer: {
+    gap: 15,
+  },
+  button: {
+    backgroundColor: '#007AFF',
+    padding: 15,
+    borderRadius: 10,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.1,
+    shadowRadius: 4,
+    elevation: 3,
+  },
+  buttonText: {
+    color: 'white',
+    fontSize: 16,
+    fontWeight: '600',
+    textAlign: 'center',
+  },
+  buttonSubtext: {
+    color: 'rgba(255, 255, 255, 0.8)',
+    fontSize: 12,
+    textAlign: 'center',
+    marginTop: 2,
+  },
+  infoContainer: {
+    backgroundColor: 'white',
+    padding: 20,
+    borderRadius: 10,
+    marginTop: 30,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 1 },
+    shadowOpacity: 0.1,
+    shadowRadius: 2,
+    elevation: 2,
+  },
+  infoTitle: {
+    fontSize: 18,
+    fontWeight: '600',
+    marginBottom: 10,
+    color: '#333',
+  },
+  infoText: {
+    fontSize: 14,
+    color: '#666',
+    marginBottom: 5,
+  },
+  codeContainer: {
+    backgroundColor: '#f8f9fa',
+    padding: 15,
+    borderRadius: 8,
+    marginTop: 20,
+    borderLeftWidth: 4,
+    borderLeftColor: '#007AFF',
+  },
+  codeTitle: {
+    fontSize: 16,
+    fontWeight: '600',
+    marginBottom: 10,
+    color: '#333',
+  },
+  codeText: {
+    fontSize: 12,
+    color: '#555',
+    fontFamily: 'monospace',
+    lineHeight: 18,
+  },
+  exampleDialog: {
+    position: 'absolute',
+    top: '50%',
+    left: 20,
+    right: 20,
+    backgroundColor: 'white',
+    borderRadius: 12,
+    padding: 20,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 4 },
+    shadowOpacity: 0.25,
+    shadowRadius: 8,
+    elevation: 8,
+  },
+  dialogTitle: {
+    fontSize: 20,
+    fontWeight: 'bold',
+    marginBottom: 15,
+    color: '#333',
+  },
+  dialogContent: {
+    fontSize: 16,
+    color: '#666',
+    marginBottom: 20,
+    lineHeight: 22,
+  },
+  dialogActions: {
+    flexDirection: 'row',
+    justifyContent: 'flex-end',
+    gap: 10,
+  },
+  dialogButton: {
+    paddingHorizontal: 20,
+    paddingVertical: 10,
+    borderRadius: 6,
+    backgroundColor: '#f0f0f0',
+  },
+  primaryButton: {
+    backgroundColor: '#007AFF',
+  },
+  dialogButtonText: {
+    fontSize: 16,
+    fontWeight: '600',
+    color: '#333',
+  },
+});
+
+export default HOCDialogExample; 

package/src/index.ts

@@ -15,9 +15,13 @@ import { NitroModules } from 'react-native-nitro-modules'
 import type { AcousticConnectRN as AcousticConnectRNSpec } from './specs/react-native-acoustic-connect.nitro'
 import Connect from './components/Connect'
 import KeyboardListener from './utils/KeyboardListener'
+import DialogListener from './utils/DialogListener'
+import useDialogTracking from './utils/useDialogTracking'
+import { withAcousticAutoDialog } from './utils/withAcousticAutoDialog'
+import DialogDebugger from './utils/DialogDebugger'
 import TLTRN from './TLTRN'
 
 const AcousticConnectRN = NitroModules.createHybridObject<AcousticConnectRNSpec>('AcousticConnectRN')
 
-export { Connect, TLTRN, KeyboardListener} 
+export { Connect, TLTRN, KeyboardListener, DialogListener, useDialogTracking, DialogDebugger, withAcousticAutoDialog }
 export default AcousticConnectRN

package/src/specs/react-native-acoustic-connect.nitro.ts

@@ -39,4 +39,9 @@ export interface AcousticConnectRN extends HybridObject<{ ios: 'swift', android:
     logScreenViewContextLoad(logicalPageName: string | null | undefined, referrer:string | null | undefined): boolean
     logScreenViewContextUnload(logicalPageName: string | null | undefined, referrer:string | null | undefined): boolean
     logScreenLayout(name: string, delay: number): boolean
+    // New dialog event handling methods
+    logDialogShowEvent(dialogId: string, dialogTitle: string, dialogType: string): boolean
+    logDialogDismissEvent(dialogId: string, dismissReason: string): boolean
+    logDialogButtonClickEvent(dialogId: string, buttonText: string, buttonIndex: number): boolean
+    logDialogCustomEvent(dialogId: string, eventName: string, values: Record<string, string | number | boolean>): boolean
 }