DocsDevelopers

URL parameters, constants and functions

Addresses that open the builder or a test mode, wp-config.php constants, PHP functions for snippets and forms, and the JavaScript API and browser events.

URL parameters#

Address	Does
`/?nativeai=edit&post=ID`	Opens the builder on a post, page or template.
`/?nativeai=edit&mode=site`	Opens the builder on Create Website With AI.
`&panel=ai&prompt=…`	Opens the builder with a request written in the assistant (not sent).
`&panel=theme`	Opens the builder on Theme Styles.
`?nativeai_template=ID`	Previews a template’s working copy on a page it applies to.
`?nai_site_draft=1`	Previews the draft site (administrators).
`?nai_popup=ID&nai_popup_mode=open`	Shows a popup open over the page, with its latest changes.
`?nai_popup=ID&nai_popup_mode=test`	Arms a popup’s triggers, ignoring its conditions and frequency.
`?nai_popups=debug`	Shows editors why each popup did or didn’t open.
`?nai_safe_mode=1` / `=off`	Code Snippets safe mode for your browser, 12 hours (administrators).

Constants (wp-config.php)#

Constant	Does
`NATIVE_AI_SECRET_KEY`	The key that encrypts integration and data-source secrets. Set it before connecting integrations; changing it means entering secrets again. Without it, a key is derived from the site’s salts.
`NATIVE_AI_SAFE_MODE`	`true` stops every snippet; `'php'` only PHP snippets. Stays on until removed.
`NATIVE_AI_SAAS_URL`	The AI service address, for self-hosting (https only). Settings → Advanced → AI service URL does the same.

define( 'NATIVE_AI_SECRET_KEY', 'a long random string' );
define( 'NATIVE_AI_SAFE_MODE', 'php' );

PHP functions#

Function	Returns or does
`nai_var( $name, $fallback = null )`	A snippet variable’s value (Code Snippets → Variables).
`nai_secret( $name, $fallback = null )`	A snippet secret, decrypted — for PHP only; never print it into a page.
`nai_config( $key, $fallback = null )`	The value of an active JSON config snippet.
`nai_log( $message, $level = 'error', $context = [] )`	Writes to the running snippet’s log (error, warning or info). Secrets are redacted.
`register_form_action( $type, $definition )`	Adds an action forms can run after a submit.
`register_form_integration( $provider )`	Adds an integration: a connection type in Integrations, with its own actions.
`register_form_field( $element_type, $info )`	Tells the form pipeline about a custom field element: its value shape (text, choice, number, bool, file, parts) and how to collect and validate it.
`register_form_tag( $name, $resolver, $label = '' )`	Adds a tag for action settings: `{name}` or `{name:argument}`.

Register form actions and integrations on the nativeai_register_form_actions and nativeai_register_form_integrations actions. An action type declares its settings as a schema, so the form editor shows it with the same controls as the built-in ones.

JavaScript#

API	Does
`naiAnalytics.track( name, { category, label, value } )`	Counts a custom Analytics event (lowercase names with underscores).
`naiAnalytics.consent( true )`	Gives Analytics consent when “Wait for consent” is on.
`window.NAI_CONFIG`	JSON config snippets set to “expose to JavaScript”.
`data-nai-track="event_name"`	On any element (in Custom HTML, say), counts clicks as that event when Analytics is on.

Browser events

nai:form-success — a Native AI form was sent successfully.
nai:popup-open, nai:popup-close — a popup, modal or off-canvas panel opened or closed.
menu:open, menu:close, menu:dropdown — a menu’s mobile panel or a dropdown.
nai:consent — dispatch it on document with { detail: { analytics: true } } to give Analytics consent (false withdraws it).
Custom events from the Trigger custom event interaction action, which interactions and your scripts can listen for.

The Scroll progress trigger sets the CSS custom property --nai-progress (0 to 1) on its targets, for progress bars and scroll effects.

Webhooks#

Form webhooks with a signing secret carry X-NativeAI-Signature: sha256=…, an HMAC-SHA256 of the request body with your secret.