Voor bouwers: shortcodes, hooks en REST

Shortcodes

Drie stuks. De server zet alleen een neutrale plek in de HTML, de browser vult de waarde in. Zonder herkenning zie je de terugvaltekst.

[psfid key="voornaam" fallback="beste klant"]

Toont de waarde van een veld. Met fallback geef je op wat er staat als het onbekend is, met wrap kies je het HTML-element (standaard span).

[psfid_token]

Toont alleen de anonieme code. Vooral handig om te testen of je eigen link werkt.

[psfid_if key="voornaam"]Welkom terug, {voornaam}![/psfid_if]

Toont de inhoud alleen als de waarde bekend is. Binnen het blok vervang je waarden met accolades, dus {voornaam}, {email} en zo verder. De browser ontsnapt die waarden voordat hij ze invoegt. Andere shortcodes binnen het blok worden gewoon uitgevoerd.

Als key gebruik je een standaard sleutel of een alias, zie Velden en tokens.

Smartcodes en merge tags

Wil je een waarde in het formulier zelf zetten, bijvoorbeeld als standaardwaarde van een veld, dan kan dat ook.

Fluent Forms, in de editor onder de groep Pure Smart Form ID:

{psfid.voornaam}
{psfid.email}
{psfid.phone}

Gravity Forms:

{psfid:voornaam}
{psfid_token}

Deze worden op de server ingevuld, met de gegevens van de herkende bezoeker. Staat FluentCRM data mergen aan, dan tellen de velden uit FluentCRM hier mee. Omdat er dan wel een persoonsgegeven in de HTML komt, markeert de plugin die pagina als niet te bewaren: hij stuurt Cache-Control: private, no-store mee en zet DONOTCACHEPAGE. Of je servercache of CDN daarnaar luistert bepaalt je hosting. Test dit met je cache aan, met twee verschillende bezoekers.

Het gewone vooraf invullen in de browser heeft dit nadeel niet. Gebruik smartcodes en merge tags dus alleen waar het echt nodig is. Een smartcode wordt ook ingevuld in een formulier dat je hebt uitgesloten van vooraf invullen.

Hooks en filters

• psfid/token_captured: actie na elke vastgelegde inzending. Argumenten: het ID van het token, de code, de velden uit de inzending, de bron (fluentforms of gravity) en het formulier-ID. De eigen CRM-sync van de plugin hangt op prioriteit 20.
• psfid_has_consent: filter om door te geven of er toestemming is voor de cookie. Staat standaard op false en telt alleen als Cookie consent verplicht aan staat.
• psfid_exclude_form_ids: filter met extra formulier-ID’s die niet vooraf worden ingevuld. Wordt samengevoegd met wat je in de instellingen invult.
• psfid_fc_source_fields: filter op de velden die uit FluentCRM worden gelezen. Argumenten: de velden, het contact en het e-mailadres.
• psfid_rest_rate_limit: filter op de limiet van de REST-routes. Standaard 120 aanroepen per minuut per IP-adres.
• psfid_pro_auto_update_security: filter in Pro. Geef false terug als je beveiligingsupdates van Pro niet automatisch wilt laten installeren.

Toestemming van je cookiebanner doorgeven:

add_filter( 'psfid_has_consent', function ( $toestemming ) {
    // Geef true terug zodra je cookiebanner toestemming heeft vastgelegd.
    return isset( $_COOKIE['mijn_cookiebanner'] ) && 'ja' === $_COOKIE['mijn_cookiebanner'];
} );

Alleen een paar velden uit FluentCRM overnemen:

add_filter( 'psfid_fc_source_fields', function ( $velden, $contact, $email ) {
    return array_intersect_key( $velden, array_flip( [ 'first_name', 'last_name', 'phone' ] ) );
}, 10, 3 );

Iets doen na elke inzending:

add_action( 'psfid/token_captured', function ( $token_id, $code, $velden, $bron, $formulier_id ) {
    // Jouw eigen koppeling.
}, 30, 5 );

REST

De browser haalt de gegevens op via eigen routes onder psfid/v1. De code zelf is de sleutel: er is geen login nodig.

GET  /wp-json/psfid/v1/data/{token}
GET  /wp-json/psfid/v1/ff-draft/{token}/{form_id}
GET  /wp-json/psfid/v1/gf-draft/{token}/{form_id}
POST /wp-json/psfid/v1/scrub-report

• data geeft de opgeslagen velden van een token, met de aliassen erbij.
• ff-draft geeft de velden van een concept uit Fluent Forms. Voor een uitgesloten formulier geeft hij niets terug.
• gf-draft geeft de sleutel van een concept uit Gravity Forms, zodat de browser kan doorsturen.
• scrub-report ontvangt de melding van het vangnet in de browser: de pagina en de veldnamen, geen waarden.

Alle vier sturen Cache-Control: private, no-store mee en delen de limiet per IP-adres. Boven de limiet krijg je een 429. Doe dat bij eigen uitbreidingen ook: alles wat persoonsgegevens teruggeeft hoort niet in een cache.

AI-toegang

Via Pure Core meldt de plugin functies aan in de Abilities API van WordPress, onder pure-smart-form-id/. Eigen functies: list-forms, get-statistics, get-recognition-chain, get-scrub-report, set-form-exclusion en run-cleanup. Daarnaast de algemene set: get-context, get-settings, update-settings, search-settings en get-help.

De functies geven tellingen, formuliergegevens en pagina’s terug, geen persoonsgegevens. De API Key van ActiveCampaign wordt afgedekt. Wijzigingen kunnen eerst als droge run en worden gelogd. Wat een agent mag regel je onder Pure Plugins > Hub-instellingen, kaart AI-toegang. Meer daarover bij Pure Core en AI-agents.

Techniek

• Eigen tabellen met het voorvoegsel psfid_ achter je WordPress-prefix: psfid_tokens, psfid_data en psfid_log.
• De code is 16 tekens lang en willekeurig gegenereerd. Hij is niet af te leiden uit een e-mailadres of een oplopend nummer.
• De cookie is een eigen cookie van je site, met SameSite=Lax en op https met Secure. Het script in de browser moet hem kunnen lezen, anders kan het de gegevens niet ophalen.
• Van het IP-adres bewaart de plugin alleen een gehashte versie bij het token.
• Het opruimen draait dagelijks via WP-Cron, onder de naam psfid_cleanup_cron.
• De pagina-HTML is voor elke bezoeker gelijk, zie Hoe het werkt.

Eigen naam in het beheer

Lever je de plugin onder je eigen naam, zet dan constanten in wp-config.php:

define( 'PSFID_BRAND_NAME', 'Formulierherkenning' );
define( 'PSFID_BRAND_MENU', 'Formulieren' );
define( 'PSFID_BRAND_HIDE_CREDITS', true );

De eerste verandert de naam op het dashboard en in de widget, de tweede het label in het beheermenu, de derde verbergt de regel met de maker.

Vertalen

De plugin komt met Nederlands, Engels, Duits, Frans en Spaans. De brontaal is Engels, het tekstdomein is pure-smart-form-id. Wil je een eigen tekst, gebruik dan een vertaaltool zoals Loco Translate en pas de vertaling aan in plaats van de code. De schermen van Pro zijn alleen in het Nederlands.

Terug naar Pure Smart Form ID documentatie