*/ function altorewrite_shared_capture_state_rank() { return array( 'shown' => 1, 'dismissed' => 2, 'submitted' => 3, ); } /** * Record the furthest state this INSTALLATION's card reached (a site option, as the review * prompt does: what leaves the site is a fact about the installation, never the address). * * @param string $slug The calling plugin's slug. * @param string $state One of shown|dismissed|submitted. */ function altorewrite_shared_capture_record( $slug, $state ) { $rank = altorewrite_shared_capture_state_rank(); if ( ! isset( $rank[ $state ] ) ) { return; } $key = 'ruac_alto_capture_state_' . sanitize_key( $slug ); $current = (string) get_option( $key, '' ); $have = isset( $rank[ $current ] ) ? $rank[ $current ] : 0; if ( $rank[ $state ] > $have ) { update_option( $key, $state ); } } /** * The reportable card state, or '' if the card has never rendered on this site. Sent on each * generation as `capturePrompt`; the backend treats '' as "nothing to report". * * @param string $slug The calling plugin's slug. * @return string */ function altorewrite_shared_capture_state( $slug ) { return (string) get_option( 'ruac_alto_capture_state_' . sanitize_key( $slug ), '' ); } /** * The consent record for one plugin: the exact label of the sign-up box, and its version (the * first 12 hex of the text's sha256, which ruac-backend re-computes and refuses on a mismatch). * Any change to the wording is therefore a new version by construction, never an edit in place. * The scope (release notes AND product updates) must match the privacy policy's sign-up section. * * @param string $name Human-readable plugin name, the same one the card is rendered with. * @return array{text:string,version:string} */ function altorewrite_shared_capture_consent( $name ) { $text = 'Email me ' . $name . ' release notes and product updates. I can unsubscribe at any time.'; return array( 'text' => $text, 'version' => substr( hash( 'sha256', $text ), 0, 12 ), ); } /** * How long a submission stands before the site may be asked again: the backend's retention * period, so the re-ask can only come after the address could have been deleted. * * @return int Seconds. */ function altorewrite_shared_capture_reask_after() { return 2 * YEAR_IN_SECONDS; } /** * Record a successful submission: the state and when, which the re-ask rule reads. * * @param string $slug The calling plugin's slug. */ function altorewrite_shared_capture_submitted( $slug ) { $slug = sanitize_key( $slug ); altorewrite_shared_capture_record( $slug, 'submitted' ); update_option( 'ruac_alto_capture_submitted_at_' . $slug, time() ); } /** * Whether the card should render now, for the current user. No side effects. * * @param string $slug The calling plugin's slug. * @return bool */ function altorewrite_shared_capture_eligible( $slug ) { $slug = sanitize_key( $slug ); if ( '' === $slug || ! current_user_can( 'manage_options' ) ) { return false; } // Value first: the same threshold as the review prompt, never before the user has seen // the plugin work. if ( (int) get_option( $slug . '_generation_count', 0 ) < altorewrite_shared_review_threshold() ) { return false; } // Not at the quota wall: that moment belongs to the wall notice, as it does for reviews. if ( altorewrite_shared_usage_state( $slug, '' !== altorewrite_shared_key_fingerprint( $slug ) )['walled'] ) { return false; } // Never alongside the review prompt, which wins whenever it is due. if ( altorewrite_shared_review_eligible( $slug ) ) { return false; } // Asked once: this user said no thanks. if ( get_user_meta( get_current_user_id(), 'ruac_alto_capture_dismissed_' . $slug, true ) ) { return false; } // Asked once per site, until the address could have been deleted (re-consent path): 24 months // from sign-up is the earliest the backend can delete it. $submitted_at = (int) get_option( 'ruac_alto_capture_submitted_at_' . $slug, 0 ); if ( $submitted_at && time() - $submitted_at < altorewrite_shared_capture_reask_after() ) { return false; } return true; } /** * "No thanks": a per-user, permanent dismissal, the review prompt's own scheme (nonce-checked * query arg, handled on admin_init before output). Inert on every other request. */ function altorewrite_shared_capture_maybe_dismiss() { if ( ! isset( $_GET['ruac_capture_off'] ) ) { return; } $slug = sanitize_key( wp_unslash( $_GET['ruac_capture_off'] ) ); if ( '' === $slug || ! current_user_can( 'manage_options' ) || ! check_admin_referer( 'ruac_capture_off_' . $slug ) ) { return; } update_user_meta( get_current_user_id(), 'ruac_alto_capture_dismissed_' . $slug, 1 ); altorewrite_shared_capture_record( $slug, 'dismissed' ); wp_safe_redirect( remove_query_arg( array( 'ruac_capture_off', '_wpnonce' ) ) ); exit; } add_action( 'admin_init', 'altorewrite_shared_capture_maybe_dismiss' ); /** * The per-user transient that carries a submission's outcome across the redirect. * * A transient, not a query arg: reading an outcome flag from $_GET without a nonce is the * pattern Plugin Check flags (NonceVerification.Recommended, EC2 walk 2026-10-08), and it is * the same move SEC1a made for AltoGraph's Media message. * * @param string $slug The calling plugin's slug. * @return string */ function altorewrite_shared_capture_outcome_key( $slug ) { return 'ruac_alto_capture_outcome_' . sanitize_key( $slug ) . '_' . get_current_user_id(); } /** * Store a submission's outcome for the card to show once, and return where to send the user. * * @param string $slug The calling plugin's slug. * @param string $result One of sent|invalid|unticked|failed. * @return string The plugin's settings page URL. */ function altorewrite_shared_capture_outcome_url( $slug, $result ) { set_transient( altorewrite_shared_capture_outcome_key( $slug ), sanitize_key( $result ), 5 * MINUTE_IN_SECONDS ); return admin_url( 'options-general.php?page=' . sanitize_key( $slug ) ); } /** * Render the card, or the outcome of a submission. Call on the plugin's own settings page, * directly after its usage panel and outside the settings