Skip to content

Commit 41fc44e

Browse files
mbasadimbasadi
authored
Merge pull request #45 from notificationapi-com/R4js2ANZ/3366-react-sdk-debug-mode
React SDK Debug Mode Implementation
2 parents 2b629a7 + feecd53 commit 41fc44e

File tree

12 files changed

+1175
-135
lines changed

12 files changed

+1175
-135
lines changed

‎.github/workflows/pull_request.yml

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,3 +29,17 @@ jobs:
2929

3030
- name: Build Project
3131
run: npm run build
32+
33+
- name: Install Playwright Browsers
34+
run: npx playwright install --with-deps
35+
36+
- name: Run E2E Tests
37+
run: npm run test:e2e
38+
39+
- name: Upload Playwright Report
40+
uses: actions/upload-artifact@v4
41+
if: failure()
42+
with:
43+
name: playwright-report
44+
path: playwright-report/
45+
retention-days: 30

‎.gitignore

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,3 +22,10 @@ dist-ssr
2222
*.njsproj
2323
*.sln
2424
*.sw?
25+
26+
# Playwright
27+
/test-results/
28+
/playwright-report/
29+
/blob-report/
30+
/playwright/.cache/
31+
tests/e2e/screenshots/

‎DEBUG.md

Lines changed: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,276 @@
1+
# NotificationAPI React SDK - Debug Mode
2+
3+
This document explains how to use the debug mode in the NotificationAPI React SDK to troubleshoot issues and understand what's happening under the hood.
4+
5+
## Overview
6+
7+
Debug mode provides detailed logging of all SDK operations, making it easier to:
8+
9+
- Diagnose connection issues
10+
- Track notification flow
11+
- Monitor API calls and responses
12+
- Debug WebSocket events
13+
- Identify state changes
14+
- Troubleshoot WebPush setup
15+
16+
## Enabling Debug Mode
17+
18+
### Basic Usage
19+
20+
Add the `debug` prop to your `NotificationAPIProvider`:
21+
22+
```jsx
23+
import { NotificationAPIProvider } from '@notificationapi/react';
24+
25+
function App() {
26+
return (
27+
<NotificationAPIProvider
28+
clientId="your-client-id"
29+
userId="your-user-id"
30+
debug={true} // Enable debug mode
31+
>
32+
{/* Your app components */}
33+
</NotificationAPIProvider>
34+
);
35+
}
36+
```
37+
38+
### Conditional Debug Mode
39+
40+
You can enable debug mode conditionally:
41+
42+
```jsx
43+
const debugMode =
44+
process.env.NODE_ENV === 'development' ||
45+
localStorage.getItem('notificationapi-debug') === 'true';
46+
47+
<NotificationAPIProvider
48+
clientId="your-client-id"
49+
userId="your-user-id"
50+
debug={debugMode}
51+
>
52+
{/* Your app components */}
53+
</NotificationAPIProvider>;
54+
```
55+
56+
### URL Parameter Debug Mode
57+
58+
Enable debug mode via URL parameter:
59+
60+
```jsx
61+
const urlParams = new URLSearchParams(window.location.search);
62+
const debugMode = urlParams.get('debug') === 'true';
63+
64+
<NotificationAPIProvider
65+
clientId="your-client-id"
66+
userId="your-user-id"
67+
debug={debugMode}
68+
>
69+
{/* Your app components */}
70+
</NotificationAPIProvider>;
71+
```
72+
73+
## What Gets Logged
74+
75+
When debug mode is enabled, you'll see detailed logs in the browser console for:
76+
77+
### 1. Initialization
78+
79+
- Provider setup and configuration
80+
- Client SDK initialization
81+
- User identification
82+
- WebSocket connection establishment
83+
84+
### 2. Notifications
85+
86+
- Fetching notifications (initial and pagination)
87+
- Receiving real-time notifications via WebSocket
88+
- State updates (marking as read, archived, etc.)
89+
- Notification filtering logic
90+
91+
### 3. API Calls
92+
93+
- REST API requests and responses
94+
- Preference updates
95+
- Error responses with context
96+
97+
### 4. WebPush Setup
98+
99+
- Service worker registration
100+
- Permission requests
101+
- Push subscription process
102+
- Error codes and troubleshooting guidance
103+
104+
### 5. State Management
105+
106+
- React state changes
107+
- Local storage operations
108+
- Context updates
109+
110+
## Understanding Debug Output
111+
112+
### Log Groups
113+
114+
Debug logs are organized into collapsible groups in the console:
115+
116+
```
117+
[NotificationAPI Debug] Provider initialization effect
118+
├── [NotificationAPI Debug] Resetting state and loading initial data
119+
├── [NotificationAPI Debug] Opening WebSocket connection
120+
└── [NotificationAPI Debug] Fetching user preferences
121+
```
122+
123+
### Log Levels
124+
125+
#### Info Logs (console.log)
126+
127+
- Normal operation events
128+
- State changes
129+
- Configuration details
130+
131+
#### Warning Logs (console.warn)
132+
133+
- Non-critical issues
134+
- Fallback behaviors
135+
- Missing optional features
136+
137+
#### Error Logs (console.error)
138+
139+
- Failed API calls
140+
- Connection errors
141+
- Invalid configurations
142+
- Includes error details, context, and stack traces
143+
144+
### Sample Debug Output
145+
146+
```javascript
147+
[NotificationAPI Debug] NotificationAPI Provider initializing {
148+
clientId: "your-client-id",
149+
userId: "user123",
150+
debug: true,
151+
timestamp: "2024-01-15T10:30:00.000Z"
152+
}
153+
154+
[NotificationAPI Debug] Configuration loaded {
155+
apiURL: "api.notificationapi.com",
156+
wsURL: "ws.notificationapi.com",
157+
initialLoadMaxCount: 1000,
158+
// ... other config
159+
}
160+
161+
[NotificationAPI Debug] Initializing NotificationAPI client
162+
├── [NotificationAPI Debug] Client configuration {
163+
clientId: "your-client-id",
164+
userId: "user123",
165+
host: "api.notificationapi.com",
166+
websocketHost: "ws.notificationapi.com"
167+
}
168+
├── [NotificationAPI Debug] Identifying user {
169+
email: "[email protected]"
170+
}
171+
```
172+
173+
## Troubleshooting Common Issues
174+
175+
### 1. Connection Issues
176+
177+
Look for these logs:
178+
179+
- `[NotificationAPI Debug] Opening WebSocket connection`
180+
- `[NotificationAPI Debug] Client configuration`
181+
182+
Check for errors in network connectivity or configuration.
183+
184+
### 2. No Notifications Loading
185+
186+
Check these logs:
187+
188+
- `[NotificationAPI Debug] Fetching notifications`
189+
- `[NotificationAPI Debug] Fetch successful`
190+
191+
Verify API responses and notification filtering logic.
192+
193+
### 3. WebPush Not Working
194+
195+
Look for:
196+
197+
- `[NotificationAPI Debug] Requesting web push permission`
198+
- `[NotificationAPI Debug] Service worker registration`
199+
- Error codes 18-22 for specific WebPush issues
200+
201+
### 4. Preferences Not Updating
202+
203+
Check:
204+
205+
- `[NotificationAPI Debug] Updating delivery preferences`
206+
- `[NotificationAPI Debug] Preferences updated successfully`
207+
208+
## Error Codes
209+
210+
### WebPush Error Codes
211+
212+
- **18**: Insecure context (not HTTPS)
213+
- **19**: Operation aborted (user denied)
214+
- **20**: Invalid application server key
215+
- **21**: Operation not allowed (notifications blocked)
216+
- **22**: Operation not supported (browser limitation)
217+
218+
## Advanced Usage
219+
220+
### Custom Debug Logger
221+
222+
You can create your own debug logger for custom handling:
223+
224+
```jsx
225+
import { createDebugLogger } from '@notificationapi/react';
226+
227+
const customLogger = createDebugLogger(true);
228+
customLogger.log('Custom debug message', { data: 'example' });
229+
```
230+
231+
### Filtering Debug Logs
232+
233+
Filter debug logs in the console using the search feature:
234+
235+
- `[NotificationAPI Debug]` - All debug logs
236+
- `ERROR:` - Only error logs
237+
- `WebSocket` - WebSocket-related logs
238+
- `notifications` - Notification-related logs
239+
240+
## Production Considerations
241+
242+
### Performance Impact
243+
244+
Debug mode has minimal performance impact but adds console overhead. Always disable in production:
245+
246+
```jsx
247+
const debugMode =
248+
process.env.NODE_ENV !== 'production' &&
249+
localStorage.getItem('debug') === 'true';
250+
```
251+
252+
### Security
253+
254+
Debug logs may contain sensitive information. Ensure debug mode is disabled in production environments.
255+
256+
### Log Cleanup
257+
258+
Debug logs don't persist after page refresh, but be mindful of:
259+
260+
- Memory usage in long-running applications
261+
- Console log limits in some browsers
262+
263+
## Support
264+
265+
When reporting issues, please:
266+
267+
1. Enable debug mode
268+
2. Reproduce the issue
269+
3. Copy the relevant console logs
270+
4. Include your configuration (without sensitive data)
271+
272+
This helps our support team diagnose issues quickly and provide better assistance.
273+
274+
## Example Integration
275+
276+
See the example in `src/LiveComponents.tsx` for a complete implementation with a debug mode toggle.

‎README.md

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,22 @@ The React SDK is mainly used for displaying In-App Notifications, allowing users
66

77
Please refer to our [documentations](https://docs.notificationapi.com).
88

9+
# Debug Mode
10+
11+
The SDK includes a comprehensive debug mode to help troubleshoot issues and understand SDK behavior. Enable it by adding the `debug` prop:
12+
13+
```jsx
14+
<NotificationAPIProvider
15+
clientId="your-client-id"
16+
userId="your-user-id"
17+
debug={true}
18+
>
19+
{/* Your app components */}
20+
</NotificationAPIProvider>
21+
```
22+
23+
For detailed information about debug mode, see [DEBUG.md](./DEBUG.md).
24+
925
# Development
1026

1127
1. Install dependencies:
@@ -20,6 +36,8 @@ npm install
2036
npm run dev
2137
```
2238

39+
The example application includes a debug mode toggle to demonstrate the feature.
40+
2341
# React + TypeScript + Vite
2442

2543
This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
@@ -100,7 +118,7 @@ We welcome contributions! To ensure smooth collaboration, please follow these st
100118

101119
5. **Commit and Push**
102120

103-
- Once you’ve made and tested your changes, commit them with a meaningful message:
121+
- Once you've made and tested your changes, commit them with a meaningful message:
104122
105123
```bash
106124
git add .

0 commit comments

Comments
 (0)