wpvr / vendor / linno / telemetry / examples / test-plugin / README.md

README.md in WPVR – 360 Panorama viewer and Virtual Tour Builder for WordPress 8.5.78, at vendor/linno/telemetry/examples/test-plugin/README.md

330 lines 8.9 KB

Raw Download Zip

1	# Test Telemetry Plugin
2
3	A comprehensive test WordPress plugin to demonstrate and validate all functionality of the Linno Telemetry SDK.
4
5	## Purpose
6
7	This plugin serves as both a testing tool and a reference implementation for integrating the Linno Telemetry SDK into WordPress plugins.
8
9	## Installation
10
11	### Prerequisites
12
13	- WordPress 5.0 or higher
14	- PHP 7.4 or higher
15	- PHP cURL extension enabled
16	- Composer installed
17
18	### Setup Steps
19
20	#### Option A: Testing from SDK Repository (Recommended for Development)
21
22	1. Install the Telemetry SDK dependencies (from the root of the telemetry package):
23	```bash
24	composer install
25	```
26
27	2. Create a symlink in WordPress plugins directory:
28	```bash
29	# This keeps the plugin in the SDK repo while making it available to WordPress
30	ln -s /path/to/telemetry-sdk/examples/test-plugin /path/to/wordpress/wp-content/plugins/test-telemetry-plugin
31	```
32
33	3. Configure API Key:
34	- Edit `examples/test-plugin/test-telemetry-plugin.php`
35	- Replace `test-api-key-replace-with-real-key` with your actual OpenPanel API key
36
37	4. Activate the plugin in WordPress admin (Plugins → Installed Plugins)
38
39	#### Option B: Standalone Installation (For Production Testing)
40
41	1. Copy the test plugin to WordPress:
42	```bash
43	cp -r examples/test-plugin /path/to/wordpress/wp-content/plugins/test-telemetry-plugin
44	```
45
46	2. Install dependencies in the plugin directory:
47	```bash
48	cd /path/to/wordpress/wp-content/plugins/test-telemetry-plugin
49	composer require linno/telemetry
50	```
51
52	3. Configure API Key:
53	- Edit `test-telemetry-plugin.php`
54	- Replace `test-api-key-replace-with-real-key` with your actual OpenPanel API key
55
56	4. Activate the plugin in WordPress admin (Plugins → Installed Plugins)
57
58	#### Option C: Using the Setup Script
59
60	```bash
61	cd examples/test-plugin
62	./setup.sh /path/to/wordpress
63	```
64
65	The setup script will:
66	- Verify WordPress installation
67	- Check Composer dependencies
68	- Copy plugin files
69	- Create necessary symlinks
70	- Provide next steps
71
72	## Features
73
74	### Admin Test Interface
75
76	The plugin adds a "Telemetry Test" menu item in WordPress admin with:
77
78	- Consent Status Display: Shows current opt-in/opt-out status
79	- Custom Event Testing: Form to send test events with custom properties
80	- System Information: Display of all collected system data
81	- Testing Checklist: Complete list of test scenarios
82	- Debug Information: SDK initialization status and diagnostics
83
84	### Automatic Event Tracking
85
86	The plugin demonstrates automatic event tracking:
87
88	- Post Published Event: Tracks when a post is published with post ID and type
89	- Install Event: Sent automatically when user grants consent
90	- Weekly System Info: Sent via WP-Cron (can be triggered manually)
91	- Deactivation Event: Captured when plugin is deactivated
92	- Feature Used Event: `Client::add_feature_used_event()` is used to register a `retention/feature_used` event triggered by a WordPress action hook
93
94	### Filter Demonstrations
95
96	Shows how to use SDK filters:
97
98	- `linno_telemetry_report_interval`: Customize reporting frequency
99	- `linno_telemetry_system_info`: Add custom system information
100
101	## Testing Scenarios
102
103	### 1. Complete Activation Flow with Consent
104
105	1. Activate the plugin
106	2. Notice should appear at top of admin pages
107	3. Click "Allow" button
108	4. Verify install event sent to OpenPanel
109	5. Check that consent status shows "Granted ✓"
110
111	### 2. Custom Event Tracking
112
113	1. Navigate to "Telemetry Test" menu
114	2. Enter event name (e.g., `button_clicked`)
115	3. Enter JSON properties (e.g., `{"button_id": "submit", "page": "settings"}`)
116	4. Click "Send Test Event"
117	5. Verify event appears in OpenPanel dashboard
118
119	### 3. Weekly System Info Report
120
121	1. Navigate to "Telemetry Test" menu
122	2. Click "Trigger Weekly Report" button
123	3. Verify system info event sent to OpenPanel
124	4. Check that next scheduled time is displayed
125
126	### 4. Deactivation Flow
127
128	1. Ensure consent is granted
129	2. Go to Plugins page
130	3. Click "Deactivate" on Test Telemetry Plugin
131	4. Modal should appear asking for reason
132	5. Select a reason and optionally add text
133	6. Click "Submit & Deactivate"
134	7. Verify deactivation event sent with reason data
135
136	### 5. Consent Denial Flow
137
138	1. Deactivate and reactivate the plugin (or clear consent option)
139	2. When notice appears, click "No thanks"
140	3. Try sending test events from admin page
141	4. Verify no events are sent (should show failure message)
142	5. Check OpenPanel - no events should appear
143
144	### 6. Post Publishing Event
145
146	1. Ensure consent is granted
147	2. Create a new post
148	3. Publish the post
149	4. Verify `post_published` event sent to OpenPanel with post details
150
151	## Testing with Different PHP Versions
152
153	### Using Docker
154
155	Test with multiple PHP versions using Docker:
156
157	```bash
158	# PHP 7.4
159	docker run -v $(pwd):/app -w /app php:7.4-cli php -v
160
161	# PHP 8.0
162	docker run -v $(pwd):/app -w /app php:8.0-cli php -v
163
164	# PHP 8.1
165	docker run -v $(pwd):/app -w /app php:8.1-cli php -v
166
167	# PHP 8.2
168	docker run -v $(pwd):/app -w /app php:8.2-cli php -v
169	```
170
171	### Using Local PHP Manager
172
173	If you have multiple PHP versions installed:
174
175	```bash
176	# Switch PHP version (example with Homebrew on macOS)
177	brew unlink php && brew link php@7.4
178	php -v
179
180	# Test the plugin
181	# Then switch to next version
182	brew unlink php@7.4 && brew link php@8.0
183	php -v
184	```
185
186	## Security Verification
187
188	### Nonce Verification
189
190	1. Open browser DevTools (Network tab)
191	2. Submit test event form
192	3. Check request payload includes `_wpnonce` parameter
193	4. Verify request succeeds with valid nonce
194
195	### Input Sanitization
196
197	1. Try entering HTML/JavaScript in event name: `<script>alert('xss')</script>`
198	2. Verify it's sanitized (should become `scriptalertxssscript` or similar)
199	3. Check deactivation reason textarea with special characters
200	4. Verify all input is properly sanitized
201
202	### Output Escaping
203
204	1. View page source of admin test page
205	2. Verify all dynamic content is properly escaped
206	3. Check for any unescaped variables in HTML attributes
207	4. Inspect consent notice HTML for proper escaping
208
209	### HTTPS Verification
210
211	1. Check browser console for mixed content warnings
212	2. Verify all API calls use HTTPS
213	3. Check that API key is never exposed in frontend
214
215	## Debugging
216
217	### Enable WordPress Debug Mode
218
219	Add to `wp-config.php`:
220
221	```php
222	define('WP_DEBUG', true);
223	define('WP_DEBUG_LOG', true);
224	define('WP_DEBUG_DISPLAY', false);
225	```
226
227	### Check Error Logs
228
229	```bash
230	# WordPress debug log
231	tail -f /path/to/wordpress/wp-content/debug.log
232
233	# PHP error log (location varies)
234	tail -f /var/log/php/error.log
235	```
236
237	### Common Issues
238
239	SDK Not Loading
240	- Verify Composer autoloader is present: `vendor/autoload.php`
241	- Check that `composer install` was run successfully
242	- Verify namespace is correct: `Linno\Telemetry\Client`
243
244	Events Not Sending
245	- Check consent status (must be "yes")
246	- Verify API key is set correctly
247	- Ensure cURL extension is enabled: `php -m \| grep curl`
248	- Check network tab for failed requests
249	- Review error logs for API errors
250	- Test cURL manually: `curl -I https://api.openpanel.dev/track`
251
252	Consent Notice Not Appearing
253	- Clear browser cache
254	- Check that option `test_telemetry_plugin_telemetry_opt_in` is not set
255	- Verify you're logged in as admin
256	- Check that `admin_notices` hook is firing
257
258	Deactivation Modal Not Showing
259	- Ensure consent is granted
260	- Check browser console for JavaScript errors
261	- Verify assets are being enqueued
262	- Clear browser cache
263
264	## Expected Results
265
266	### OpenPanel Events
267
268	After completing all tests, you should see these events in OpenPanel:
269
270	1. telemetry_installed - When consent is granted
271	- Contains: site_url, plugin info, system info, install_time
272
273	2. test_custom_event - From manual test form
274	- Contains: site_url, plugin info, system info, custom properties
275
276	3. post_published - When publishing a post
277	- Contains: site_url, plugin info, system info, post_id, post_type
278
279	4. system_info - From weekly cron or manual trigger
280	- Contains: site_url, plugin info, all system information
281
282	5. plugin_deactivated - When deactivating with reason
283	- Contains: site_url, plugin info, reason_category, reason_text
284
285	## Code Examples
286
287	### Basic Tracking
288
289	```php
290	// Using helper function
291	linno_telemetry_track('user_action', [
292	'action_type' => 'button_click',
293	'button_id' => 'save_settings'
294	]);
295
296	// Using client instance
297	if (isset($GLOBALS['test_telemetry_client'])) {
298	$GLOBALS['test_telemetry_client']->track('user_action', [
299	'action_type' => 'form_submit'
300	]);
301	}
302	```
303
304	### Custom Filters
305
306	```php
307	// Change reporting interval
308	add_filter('linno_telemetry_report_interval', function($interval) {
309	return 'daily'; // or 'hourly', 'twicedaily'
310	});
311
312	// Add custom system info
313	add_filter('linno_telemetry_system_info', function($info) {
314	$info['custom_field'] = 'custom_value';
315	return $info;
316	});
317	```
318
319	## Support
320
321	For issues or questions:
322	- Check the main SDK documentation in `/docs`
323	- Review the integration guide: `/docs/integration.md`
324	- Check event catalog: `/docs/event-catalog.md`
325	- Review privacy policy: `/docs/privacy.md`
326
327	## License
328
329	GPL-2.0-or-later
330