← All changes | inc/api/onboarding-api.php +194 -4 1.4.0 → 1.6.1 View file →

		@@ -6,8 +6,11 @@
6	6	* - GET /onboarding/get-status — return { completed: 'yes'|'no' }
7	7	* - POST /onboarding/set-status — write completion + optional analytics
8	8	* - POST /onboarding/create-campaign — create a published suredonation_cmpgn
9	9	* - POST /onboarding/user-details — persist lead capture (free-only step)
	10	+ * - POST /onboarding/set-tour-seen — mark the campaign guided tour seen (per-user meta)
	11	+ * - POST /onboarding/set-tour-progress — persist the tour's resume step (per-user meta)
	12	+ * - POST /onboarding/track-tour — fire the one-time "tour shown" analytics event
10	13	*
11	14	* @package SureDonation
12	15	*/
13	16
		@@ -39,8 +42,46 @@
39	42	*/
40	43	private const GOAL_TYPES = [ 'raised_amount', 'donation_count' ];
41	44
42	45	/**
	46	+ * User-meta key for the "campaign guided tour seen" flag.
	47	+ *
	48	+ * Stored per-user (not a site option) so the "seen once" state follows the
	49	+ * user across devices, unlike the onboarding completion flag.
	50	+ *
	51	+ * @since 1.5.0
	52	+ * @var string
	53	+ */
	54	+ public const TOUR_SEEN_META = 'suredonation_campaign_tour_seen';
	55	+
	56	+ /**
	57	+ * User-meta key for the campaign guided tour's resume point.
	58	+ *
	59	+ * Holds the step key the tour should resume at (empty string = no saved
	60	+ * progress). Persisted per-user so an interactive, multi-surface run
	61	+ * survives a page reload or a trip to the form builder / page editor.
	62	+ *
	63	+ * @since 1.5.0
	64	+ * @var string
	65	+ */
	66	+ public const TOUR_PROGRESS_META = 'suredonation_campaign_tour_progress';
	67	+
	68	+ /**
	69	+ * User-meta key arming the first-run tour for a specific campaign.
	70	+ *
	71	+ * Holds the campaign id whose detail page should auto-start the guided tour
	72	+ * the first time it is opened. The onboarding wizard sets this because it
	73	+ * creates a campaign and then exits via a full page reload to the dashboard
	74	+ * / payments screen — so the in-memory `justCreated` navigation flag the SPA
	75	+ * flow relies on never reaches the campaign page. Cleared once the tour is
	76	+ * seen. Absent / 0 = nothing pending.
	77	+ *
	78	+ * @since 1.5.0
	79	+ * @var string
	80	+ */
	81	+ public const TOUR_PENDING_META = 'suredonation_campaign_tour_pending';
	82	+
	83	+ /**
43	84	* Return endpoint definitions for Rest_Api to register.
44	85	*
45	86	* @return array<string,mixed>
46	87	* @since 1.0.0
		@@ -46,28 +87,66 @@
46	87	* @since 1.0.0
47	88	*/
48	89	public function get_endpoints() {
49	90	return [
50		- '/onboarding/get-status' => [
	91	+ '/onboarding/get-status' => [
51	92	'methods' => WP_REST_Server::READABLE,
52	93	'callback' => [ $this, 'get_status' ],
53	94	'permission_callback' => [ $this, 'check_permissions' ],
54	95	],
55		- '/onboarding/set-status' => [
	96	+ '/onboarding/set-status' => [
56	97	'methods' => WP_REST_Server::EDITABLE,
57	98	'callback' => [ $this, 'set_status' ],
58	99	'permission_callback' => [ $this, 'check_permissions' ],
59	100	],
60		- '/onboarding/create-campaign' => [
	101	+ '/onboarding/create-campaign' => [
61	102	'methods' => WP_REST_Server::EDITABLE,
62	103	'callback' => [ $this, 'create_campaign' ],
63	104	'permission_callback' => [ $this, 'check_permissions' ],
64	105	],
65		- '/onboarding/user-details' => [
	106	+ '/onboarding/user-details' => [
66	107	'methods' => WP_REST_Server::EDITABLE,
67	108	'callback' => [ $this, 'save_user_details' ],
68	109	'permission_callback' => [ $this, 'check_permissions' ],
69	110	],
	111	+ '/onboarding/set-tour-seen' => [
	112	+ 'methods' => WP_REST_Server::EDITABLE,
	113	+ 'callback' => [ $this, 'set_tour_seen' ],
	114	+ 'permission_callback' => [ $this, 'check_permissions' ],
	115	+ ],
	116	+ '/onboarding/set-tour-progress' => [
	117	+ 'methods' => WP_REST_Server::EDITABLE,
	118	+ 'callback' => [ $this, 'set_tour_progress' ],
	119	+ 'permission_callback' => [ $this, 'check_permissions' ],
	120	+ ],
	121	+ '/onboarding/track-tour' => [
	122	+ 'methods' => WP_REST_Server::EDITABLE,
	123	+ 'callback' => [ $this, 'track_tour' ],
	124	+ 'permission_callback' => [ $this, 'check_permissions' ],
	125	+ 'args' => [
	126	+ // Omitted => "tour shown", the endpoint's original meaning.
	127	+ 'event' => [
	128	+ 'type' => 'string',
	129	+ 'required' => false,
	130	+ 'default' => '',
	131	+ 'validate_callback' => static function ( $value ) {
	132	+ return in_array(
	133	+ $value,
	134	+ [ '', 'shown', 'completed', 'dismissed', 'opted_out', 'manual_started' ],
	135	+ true
	136	+ );
	137	+ },
	138	+ ],
	139	+ // Free-form step key, only meaningful for `dismissed`. It is
	140	+ // sent on to analytics, so keep it to a bounded slug.
	141	+ 'step' => [
	142	+ 'type' => 'string',
	143	+ 'required' => false,
	144	+ 'default' => '',
	145	+ 'sanitize_callback' => 'sanitize_key',
	146	+ ],
	147	+ ],
	148	+ ],
70	149	];
71	150	}
72	151
73	152	/**
		@@ -210,8 +289,14 @@
210	289	'goal_amount' => $goal_amount,
211	290	]
212	291	);
213	292
	293	+ // Arm the first-run tour for this campaign: the wizard leaves via a full
	294	+ // page reload, so the SPA's transient `justCreated` flag never reaches the
	295	+ // campaign page. The pending pointer makes the tour fire the first time the
	296	+ // user opens this campaign's detail page instead.
	297	+ update_user_meta( get_current_user_id(), self::TOUR_PENDING_META, $campaign_id );
	298	+
214	299	return new WP_REST_Response(
215	300	[
216	301	'success' => true,
217	302	'campaign_id' => $campaign_id,
		@@ -258,8 +343,113 @@
258	343	*
259	344	* @param array<string,mixed> $payload Sanitised payload.
260	345	*/
261	346	do_action( 'suredonation_onboarding_user_details_saved', $payload );
	347	+
	348	+ return new WP_REST_Response( [ 'success' => true ] );
	349	+ }
	350	+
	351	+ /**
	352	+ * POST /onboarding/set-tour-seen.
	353	+ *
	354	+ * Marks the campaign guided tour as seen for the current user so it does
	355	+ * not reappear on future campaign creations. Written when the user either
	356	+ * completes the tour or opts out via "Don't show again".
	357	+ *
	358	+ * @return WP_REST_Response
	359	+ * @since 1.5.0
	360	+ */
	361	+ public function set_tour_seen() {
	362	+ $user_id = get_current_user_id();
	363	+ update_user_meta( $user_id, self::TOUR_SEEN_META, 'yes' );
	364	+ // The tour is finished with — drop any saved resume point and the
	365	+ // wizard's pending pointer so neither can re-trigger it.
	366	+ delete_user_meta( $user_id, self::TOUR_PROGRESS_META );
	367	+ delete_user_meta( $user_id, self::TOUR_PENDING_META );
	368	+
	369	+ return new WP_REST_Response( [ 'success' => true ] );
	370	+ }
	371	+
	372	+ /**
	373	+ * POST /onboarding/set-tour-progress.
	374	+ *
	375	+ * Persists the step the guided tour should resume at (per-user), so an
	376	+ * interactive run survives a reload or a trip to another screen. Stored as
	377	+ * `"<campaign_id>:<step>"` so a run only resumes on the campaign it started
	378	+ * on. An empty `step` (or missing campaign) clears the saved point.
	379	+ *
	380	+ * @param WP_REST_Request $request Request.
	381	+ * @return WP_REST_Response
	382	+ * @since 1.5.0
	383	+ */
	384	+ public function set_tour_progress( $request ) {
	385	+ $user_id = get_current_user_id();
	386	+ $step = sanitize_key( (string) $request->get_param( 'step' ) );
	387	+ $campaign_id = absint( $request->get_param( 'campaign_id' ) );
	388	+
	389	+ if ( '' === $step || $campaign_id <= 0 ) {
	390	+ delete_user_meta( $user_id, self::TOUR_PROGRESS_META );
	391	+ } else {
	392	+ update_user_meta( $user_id, self::TOUR_PROGRESS_META, $campaign_id . ':' . $step );
	393	+ }
	394	+
	395	+ return new WP_REST_Response( [ 'success' => true ] );
	396	+ }
	397	+
	398	+ /**
	399	+ * POST /onboarding/track-tour.
	400	+ *
	401	+ * Signals a campaign guided-tour analytics moment. With no `event` param this
	402	+ * means "the tour was shown", which is what the endpoint did originally and
	403	+ * what an older script bundle still sends. An `event` param instead reports
	404	+ * how a run ended (completed / dismissed / opted_out) or that a replay was
	405	+ * started manually.
	406	+ *
	407	+ * The actions below fire on every call; the built-in analytics listener
	408	+ * decides what to record and how often (the BSF events tracker dedups by
	409	+ * event name), so repeat calls are cheap.
	410	+ *
	411	+ * @param \WP_REST_Request<array<string,mixed>>|null $request Request object. A
	412	+ * missing request is treated as the bare "shown" signal, so the
	413	+ * endpoint's original no-argument contract still holds.
	414	+ * @return WP_REST_Response
	415	+ * @since 1.5.0
	416	+ */
	417	+ public function track_tour( $request = null ) {
	418	+ // Both params are read up front so the outcome branch below does not have
	419	+ // to re-establish that the request exists.
	420	+ $event = '';
	421	+ $step = '';
	422	+
	423	+ if ( $request instanceof WP_REST_Request ) {
	424	+ $event = Helper::get_string_value( $request->get_param( 'event' ) );
	425	+ $step = Helper::get_string_value( $request->get_param( 'step' ) );
	426	+ }
	427	+
	428	+ if ( '' === $event || 'shown' === $event ) {
	429	+ /**
	430	+ * Fires whenever the campaign guided tour is shown (i.e. on every call
	431	+ * to this endpoint). The built-in listener dedups recording per site;
	432	+ * additional listeners run on each fire and must dedup themselves if
	433	+ * they need once-only behavior.
	434	+ *
	435	+ * @since 1.5.0
	436	+ */
	437	+ do_action( 'suredonation_campaign_tour_shown' );
	438	+
	439	+ return new WP_REST_Response( [ 'success' => true ] );
	440	+ }
	441	+
	442	+ /**
	443	+ * Fires when a campaign guided-tour run ends, or when a manual replay
	444	+ * starts.
	445	+ *
	446	+ * @param string $event The outcome: 'completed', 'dismissed',
	447	+ * 'opted_out' or 'manual_started'.
	448	+ * @param string $step Step key the run ended on; empty when not applicable.
	449	+ * @since 1.5.0
	450	+ */
	451	+ do_action( 'suredonation_campaign_tour_outcome', $event, $step );
262	452
263	453	return new WP_REST_Response( [ 'success' => true ] );
264	454	}
265	455