Skip to content

Beautiful Open-Source Form Builder

Capture native campaign attribution on submissions (#1247)

Julien Nahumc91db0f70a45
diff --git a/api/app/Events/Forms/FormSubmitted.php b/api/app/Events/Forms/FormSubmitted.php
index e0e5aa890..57ab47eb2 100644
--- a/api/app/Events/Forms/FormSubmitted.php
+++ b/api/app/Events/Forms/FormSubmitted.php
@@ -17,14 +17,17 @@ class FormSubmitted
public $data;
+ public array $meta;
+
/**
* Create a new event instance.
*
* @return void
*/
- public function __construct(Form $form, array $data)
+ public function __construct(Form $form, array $data, array $meta = [])
{
$this->form = $form;
$this->data = $data;
+ $this->meta = $meta;
}
}
diff --git a/api/app/Http/Controllers/Integrations/Zapier/IntegrationController.php b/api/app/Http/Controllers/Integrations/Zapier/IntegrationController.php
index 86d0f1a53..62784a5d8 100644
--- a/api/app/Http/Controllers/Integrations/Zapier/IntegrationController.php
+++ b/api/app/Http/Controllers/Integrations/Zapier/IntegrationController.php
@@ -60,7 +60,11 @@ class IntegrationController
}
$cacheKey = "zapier-poll-submissions-{$form->id}";
return (array) Cache::remember($cacheKey, 60 * 5, function () use ($form, $submissionData, $lastSubmission) {
- return [ZapierIntegration::formatWebhookData($form, $submissionData ?? $lastSubmission->data)];
+ return [ZapierIntegration::formatWebhookData(
+ $form,
+ $submissionData ?? $lastSubmission->data,
+ $lastSubmission?->meta ?? []
+ )];
});
}
}
diff --git a/api/app/Http/Requests/AnswerFormRequest.php b/api/app/Http/Requests/AnswerFormRequest.php
index a822edaa9..2e01af69d 100644
--- a/api/app/Http/Requests/AnswerFormRequest.php
+++ b/api/app/Http/Requests/AnswerFormRequest.php
@@ -12,6 +12,7 @@ use App\Rules\ValidPhoneInputRule;
use App\Rules\ValidReCaptcha;
use App\Rules\ValidUrl;
use App\Service\Forms\FormLogicPropertyResolver;
+use App\Service\Forms\SubmissionAttribution;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Http\Request;
use Illuminate\Support\Str;
@@ -144,6 +145,8 @@ class AnswerFormRequest extends FormRequest
// Add rules for metadata fields
$this->requestRules['completion_time'] = 'nullable|integer';
$this->requestRules['submission_id'] = 'nullable|string';
+ $this->requestRules['tracking_parameters'] = 'nullable|array:' . implode(',', SubmissionAttribution::PARAMETERS);
+ $this->requestRules['tracking_parameters.*'] = 'nullable|string|max:' . SubmissionAttribution::MAX_VALUE_LENGTH;
return $this->requestRules;
}
diff --git a/api/app/Http/Requests/FormSubmissionExportRequest.php b/api/app/Http/Requests/FormSubmissionExportRequest.php
index e5bd065e0..a3c18bb11 100644
--- a/api/app/Http/Requests/FormSubmissionExportRequest.php
+++ b/api/app/Http/Requests/FormSubmissionExportRequest.php
@@ -6,6 +6,7 @@ use App\Models\Forms\Form;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Http\Request;
use Illuminate\Validation\Rule;
+use App\Service\Forms\SubmissionAttribution;
class FormSubmissionExportRequest extends FormRequest
{
@@ -24,6 +25,9 @@ class FormSubmissionExportRequest extends FormRequest
))->pluck('id')->toArray();
$validColumns[] = 'created_at';
$validColumns[] = 'status';
+ foreach (SubmissionAttribution::PARAMETERS as $parameter) {
+ $validColumns[] = SubmissionAttribution::columnId($parameter);
+ }
return [
'columns' => [
diff --git a/api/app/Http/Resources/FormSubmissionResource.php b/api/app/Http/Resources/FormSubmissionResource.php
index daac7ce8a..d1c041d36 100644
--- a/api/app/Http/Resources/FormSubmissionResource.php
+++ b/api/app/Http/Resources/FormSubmissionResource.php
@@ -30,14 +30,21 @@ class FormSubmissionResource extends JsonResource
$this->addExtraData();
}
- return array_merge([
- 'data' => $this->data,
- 'completion_time' => $this->completion_time,
- ], ($this->publiclyAccessed) ? [] : [
+ $privateData = [
'form_id' => $this->form_id,
'id' => $this->id,
'submission_id' => SubmissionUrlService::getSubmissionIdentifier($this->resource),
- ]);
+ ];
+
+ $attribution = ($this->meta ?? [])['attribution'] ?? null;
+ if (is_array($attribution) && !empty($attribution)) {
+ $privateData['meta'] = ['attribution' => $attribution];
+ }
+
+ return array_merge([
+ 'data' => $this->data,
+ 'completion_time' => $this->completion_time,
+ ], ($this->publiclyAccessed) ? [] : $privateData);
}
public function publiclyAccessed($publiclyAccessed = true)
diff --git a/api/app/Integrations/Handlers/AbstractIntegrationHandler.php b/api/app/Integrations/Handlers/AbstractIntegrationHandler.php
index f708f054c..0779310af 100644
--- a/api/app/Integrations/Handlers/AbstractIntegrationHandler.php
+++ b/api/app/Integrations/Handlers/AbstractIntegrationHandler.php
@@ -19,6 +19,7 @@ abstract class AbstractIntegrationHandler
{
protected $form = null;
protected $submissionData = null;
+ protected array $submissionMeta = [];
protected $integrationData = null;
protected $provider = null;
protected ?array $computedValues = null;
@@ -30,6 +31,7 @@ abstract class AbstractIntegrationHandler
) {
$this->form = $event->form;
$this->submissionData = $event->data;
+ $this->submissionMeta = $event->meta;
$this->integrationData = $formIntegration->data;
$this->provider = $formIntegration->provider;
}
@@ -80,7 +82,7 @@ abstract class AbstractIntegrationHandler
*/
protected function getWebhookData(): array
{
- return self::formatWebhookData($this->form, $this->submissionData);
+ return self::formatWebhookData($this->form, $this->submissionData, $this->submissionMeta);
}
final public function run(): void
@@ -135,7 +137,7 @@ abstract class AbstractIntegrationHandler
return [];
}
- public static function formatWebhookData(Form $form, array $submissionData): array
+ public static function formatWebhookData(Form $form, array $submissionData, array $submissionMeta = []): array
{
$formatter = (new FormSubmissionFormatter($form, $submissionData))
->useSignedUrlForFiles()
@@ -171,6 +173,11 @@ abstract class AbstractIntegrationHandler
$data['edit_link'] = SubmissionUrlService::buildEditUrl($form, $submissionData['submission_id']);
}
+ $attribution = $submissionMeta['attribution'] ?? null;
+ if (is_array($attribution) && !empty($attribution)) {
+ $data['meta'] = ['attribution' => $attribution];
+ }
+
return $data;
}
diff --git a/api/app/Jobs/Form/StoreFormSubmissionJob.php b/api/app/Jobs/Form/StoreFormSubmissionJob.php
index c24bb879e..0cbfa368d 100644
--- a/api/app/Jobs/Form/StoreFormSubmissionJob.php
+++ b/api/app/Jobs/Form/StoreFormSubmissionJob.php
@@ -11,6 +11,7 @@ use App\Models\Forms\FormSubmission;
use App\Service\Billing\Feature;
use App\Service\Forms\FormAutoIncrementSequence;
use App\Service\Forms\FormLogicPropertyResolver;
+use App\Service\Forms\SubmissionAttribution;
use App\Service\Storage\FilenameUrlEncoder;
use App\Service\Storage\StorageFileNameParser;
use Illuminate\Bus\Queueable;
@@ -64,6 +65,8 @@ class StoreFormSubmissionJob implements ShouldQueue
private bool $isPartial = false;
private bool $isClientProvidedSubmissionId = false;
private ?string $submitterIp = null;
+ private array $attribution = [];
+ private array $storedMeta = [];
/**
* Create a new job instance.
@@ -89,7 +92,7 @@ class StoreFormSubmissionJob implements ShouldQueue
$this->storeSubmission($this->formData);
$this->formData['submission_id'] = $this->submissionId;
if (!$this->isPartial) {
- FormSubmitted::dispatch($this->form, $this->formData);
+ FormSubmitted::dispatch($this->form, $this->formData, $this->storedMeta);
}
}
@@ -104,6 +107,11 @@ class StoreFormSubmissionJob implements ShouldQueue
*/
private function extractMetadata(): void
{
+ $this->attribution = app(SubmissionAttribution::class)->sanitize(
+ $this->submissionData['tracking_parameters'] ?? null
+ );
+ unset($this->submissionData['tracking_parameters']);
+
if (isset($this->submissionData['completion_time'])) {
$this->completionTime = $this->submissionData['completion_time'];
unset($this->submissionData['completion_time']);
@@ -205,6 +213,8 @@ class StoreFormSubmissionJob implements ShouldQueue
$submission->form_id = $this->form->id;
}
+ $isNewSubmission = !$submission->exists;
+
if ($this->isPartial) {
foreach ($formData as $fieldId => $value) {
if ($value === self::AUTO_INCREMENT_ID_PLACEHOLDER) {
@@ -246,14 +256,26 @@ class StoreFormSubmissionJob implements ShouldQueue
$submission->public_id = Str::uuid()->toString();
}
+ $existingMeta = $submission->meta ?? [];
+ $metaChanged = false;
+
+ if ($isNewSubmission && !empty($this->attribution)) {
+ $existingMeta['attribution'] = $this->attribution;
+ $metaChanged = true;
+ }
+
if ($this->form->enable_ip_tracking && $this->form->workspace->hasFeature('enable_ip_tracking') && $this->submitterIp) {
- $existingMeta = $submission->meta ?? [];
$existingMeta['ip_address'] = $this->submitterIp;
+ $metaChanged = true;
+ }
+
+ if ($metaChanged) {
$submission->meta = $existingMeta;
}
$submission->save();
$this->submissionId = $submission->id;
+ $this->storedMeta = $submission->meta ?? [];
});
}
diff --git a/api/app/Service/Forms/FormExportService.php b/api/app/Service/Forms/FormExportService.php
index f5c51a249..1218c7f39 100644
--- a/api/app/Service/Forms/FormExportService.php
+++ b/api/app/Service/Forms/FormExportService.php
@@ -56,6 +56,11 @@ class FormExportService
foreach ($displayColumns as $column => $value) {
if ($value === true) {
+ if ($parameter = SubmissionAttribution::parameterFromColumnId($column)) {
+ $filteredData[$parameter] = $submission->meta['attribution'][$parameter] ?? '';
+ continue;
+ }
+
$key = collect($formattedData)->keys()->first(fn ($key) => str_contains($key, $column));
if ($key) {
$filteredData[$key] = $formattedData[$key];
diff --git a/api/app/Service/Forms/SubmissionAttribution.php b/api/app/Service/Forms/SubmissionAttribution.php
new file mode 100644
index 000000000..0bcbe5fb3
--- /dev/null
+++ b/api/app/Service/Forms/SubmissionAttribution.php
@@ -0,0 +1,72 @@
+<?php
+
+namespace App\Service\Forms;
+
+class SubmissionAttribution
+{
+ public const MAX_VALUE_LENGTH = 2048;
+
+ public const PARAMETERS = [
+ 'utm_source',
+ 'utm_medium',
+ 'utm_campaign',
+ 'utm_id',
+ 'utm_term',
+ 'utm_content',
+ 'utm_source_platform',
+ 'utm_creative_format',
+ 'utm_marketing_tactic',
+ 'gclid',
+ 'gbraid',
+ 'wbraid',
+ 'dclid',
+ 'fbclid',
+ 'ttclid',
+ 'msclkid',
+ ];
+
+ /**
+ * Keep only supported, non-empty attribution values.
+ */
+ public function sanitize(mixed $parameters): array
+ {
+ if (!is_array($parameters)) {
+ return [];
+ }
+
+ $attribution = [];
+
+ foreach (self::PARAMETERS as $parameter) {
+ $value = $parameters[$parameter] ?? null;
+
+ if (!is_string($value) || trim($value) === '') {
+ continue;
+ }
+
+ if (mb_strlen($value) > self::MAX_VALUE_LENGTH) {
+ continue;
+ }
+
+ $attribution[$parameter] = $value;
+ }
+
+ return $attribution;
+ }
+
+ public static function columnId(string $parameter): string
+ {
+ return 'meta.attribution.' . $parameter;
+ }
+
+ public static function parameterFromColumnId(string $columnId): ?string
+ {
+ $prefix = 'meta.attribution.';
+ if (!str_starts_with($columnId, $prefix)) {
+ return null;
+ }
+
+ $parameter = substr($columnId, strlen($prefix));
+
+ return in_array($parameter, self::PARAMETERS, true) ? $parameter : null;
+ }
+}
diff --git a/api/tests/Feature/Forms/FormSubmissionExportTest.php b/api/tests/Feature/Forms/FormSubmissionExportTest.php
index e4d7cdf95..29453910a 100644
--- a/api/tests/Feature/Forms/FormSubmissionExportTest.php
+++ b/api/tests/Feature/Forms/FormSubmissionExportTest.php
@@ -3,6 +3,7 @@
use App\Models\User;
use App\Models\Forms\FormSubmission;
use App\Service\Forms\FormExportService;
+use App\Service\Forms\SubmissionAttribution;
use App\Service\Storage\FileUploadPathService;
use Carbon\Carbon;
use Illuminate\Routing\Middleware\ThrottleRequests;
@@ -72,6 +73,44 @@ it('can export form submissions with selected columns', function () {
->assertHeader('content-disposition', 'attachment; filename=' . $form->slug . '-submission-data.csv');
});
+it('exports selected attribution columns and leaves unselected attribution out', function () {
+ $user = $this->actingAsProUser();
+ $workspace = $this->createUserWorkspace($user);
+ $form = $this->createForm($user, $workspace);
+ $textField = collect($form->properties)->firstWhere('type', 'text');
+
+ $submissionData = $this->generateFormSubmissionData($form, [
+ $textField['id'] => 'Attributed submission',
+ ]);
+ $submissionData['tracking_parameters'] = [
+ 'utm_source' => 'newsletter',
+ 'gclid' => 'not-exported',
+ ];
+
+ $this->postJson(route('forms.answer', $form->slug), $submissionData)
+ ->assertSuccessful();
+
+ $response = $this->postJson(route('open.forms.submissions.export', [
+ 'form' => $form,
+ ]), [
+ 'columns' => [
+ $textField['id'] => true,
+ SubmissionAttribution::columnId('utm_source') => true,
+ ],
+ ]);
+
+ $response->assertSuccessful();
+
+ ob_start();
+ $response->sendContent();
+ $rows = parseCsvRows(ob_get_clean());
+
+ expect($rows[0])->toContain('utm_source')
+ ->not->toContain('gclid')
+ ->and($rows[1])->toContain('newsletter')
+ ->not->toContain('not-exported');
+});
+
it('exports only the selected submission ids', function () {
$user = $this->actingAsProUser();
$workspace = $this->createUserWorkspace($user);
diff --git a/api/tests/Feature/Submissions/SubmissionAttributionTest.php b/api/tests/Feature/Submissions/SubmissionAttributionTest.php
new file mode 100644
index 000000000..e451be8d3
--- /dev/null
+++ b/api/tests/Feature/Submissions/SubmissionAttributionTest.php
@@ -0,0 +1,138 @@
+<?php
+
+use App\Http\Resources\FormSubmissionResource;
+use App\Integrations\Handlers\AbstractIntegrationHandler;
+use App\Models\Forms\FormSubmission;
+use App\Service\Forms\SubmissionAttribution;
+
+function attributionSubmissionData($test, $form, array $overrides = []): array
+{
+ $nameField = collect($form->properties)->firstWhere('type', 'text');
+
+ return $test->generateFormSubmissionData($form, [
+ $nameField['id'] => 'Attributed submission',
+ ...$overrides,
+ ]);
+}
+
+it('stores every supported attribution parameter outside submission data', function () {
+ $user = $this->actingAsUser();
+ $workspace = $this->createUserWorkspace($user);
+ $form = $this->createForm($user, $workspace);
+ $trackingParameters = collect(SubmissionAttribution::PARAMETERS)
+ ->mapWithKeys(fn (string $parameter) => [$parameter => $parameter . '-value'])
+ ->all();
+
+ $payload = attributionSubmissionData($this, $form);
+ $payload['tracking_parameters'] = $trackingParameters;
+
+ $this->postJson(route('forms.answer', $form->slug), $payload)->assertSuccessful();
+
+ $submission = $form->submissions()->firstOrFail();
+ expect($submission->meta['attribution'])->toBe($trackingParameters)
+ ->and($submission->data)->not->toHaveKey('tracking_parameters');
+});
+
+it('rejects unsupported, non-string, and oversized attribution values', function (array $trackingParameters, string $errorKey) {
+ $user = $this->actingAsUser();
+ $workspace = $this->createUserWorkspace($user);
+ $form = $this->createForm($user, $workspace);
+ $payload = attributionSubmissionData($this, $form);
+ $payload['tracking_parameters'] = $trackingParameters;
+
+ $this->postJson(route('forms.answer', $form->slug), $payload)
+ ->assertStatus(422)
+ ->assertJsonValidationErrors([$errorKey]);
+})->with([
+ 'unsupported key' => [['secret_token' => 'do-not-store'], 'tracking_parameters'],
+ 'non-string value' => [['utm_source' => ['google']], 'tracking_parameters.utm_source'],
+ 'oversized value' => [['gclid' => str_repeat('x', SubmissionAttribution::MAX_VALUE_LENGTH + 1)], 'tracking_parameters.gclid'],
+]);
+
+it('does not create attribution metadata for empty values', function () {
+ $user = $this->actingAsUser();
+ $workspace = $this->createUserWorkspace($user);
+ $form = $this->createForm($user, $workspace);
+ $payload = attributionSubmissionData($this, $form);
+ $payload['tracking_parameters'] = ['utm_source' => ' ', 'gclid' => ''];
+
+ $this->postJson(route('forms.answer', $form->slug), $payload)->assertSuccessful();
+
+ expect($form->submissions()->firstOrFail()->meta)->toBeNull();
+});
+
+it('keeps first-touch attribution across partial completion', function () {
+ $user = $this->actingAsBusinessUser();
+ $workspace = $this->createUserWorkspace($user);
+ $form = $this->createForm($user, $workspace, ['enable_partial_submissions' => true]);
+
+ $partialPayload = attributionSubmissionData($this, $form);
+ $partialPayload['is_partial'] = true;
+ $partialPayload['tracking_parameters'] = ['utm_source' => 'first-touch'];
+ $partialResponse = $this->postJson(route('forms.answer', $form->slug), $partialPayload)
+ ->assertSuccessful();
+
+ $completePayload = attributionSubmissionData($this, $form);
+ $completePayload['submission_hash'] = $partialResponse->json('submission_hash');
+ $completePayload['tracking_parameters'] = [
+ 'utm_source' => 'later-touch',
+ 'utm_campaign' => 'must-not-be-added',
+ ];
+ $this->postJson(route('forms.answer', $form->slug), $completePayload)->assertSuccessful();
+
+ $submission = $form->submissions()->firstOrFail();
+ expect($submission->status)->toBe(FormSubmission::STATUS_COMPLETED)
+ ->and($submission->meta['attribution'])->toBe(['utm_source' => 'first-touch']);
+});
+
+it('does not allow an admin edit to change attribution', function () {
+ $user = $this->actingAsUser();
+ $workspace = $this->createUserWorkspace($user);
+ $form = $this->createForm($user, $workspace);
+ $payload = attributionSubmissionData($this, $form);
+ $payload['tracking_parameters'] = ['utm_source' => 'original'];
+ $this->postJson(route('forms.answer', $form->slug), $payload)->assertSuccessful();
+
+ $submission = $form->submissions()->firstOrFail();
+ $editPayload = attributionSubmissionData($this, $form);
+ $editPayload['tracking_parameters'] = ['utm_source' => 'admin-change'];
+ $this->putJson(route('open.forms.submissions.update', [$form, $submission->id]), $editPayload)
+ ->assertSuccessful();
+
+ expect($submission->fresh()->meta['attribution'])->toBe(['utm_source' => 'original']);
+});
+
+it('exposes attribution to owners but not publicly', function () {
+ $user = $this->actingAsUser();
+ $workspace = $this->createUserWorkspace($user);
+ $form = $this->createForm($user, $workspace);
+ $submission = $form->submissions()->create([
+ 'data' => [],
+ 'status' => FormSubmission::STATUS_COMPLETED,
+ 'meta' => ['attribution' => ['utm_source' => 'newsletter']],
+ ]);
+
+ $ownerResponse = $this->getJson(route('open.forms.submissions.fetch', [$form, $submission->id]))
+ ->assertSuccessful();
+ expect($ownerResponse->json('meta.attribution.utm_source'))->toBe('newsletter');
+
+ $submission->setRelation('form', $form);
+ $publicData = (new FormSubmissionResource($submission))->publiclyAccessed()->resolve();
+ expect($publicData)->not->toHaveKey('meta');
+});
+
+it('adds attribution to machine integration payloads without changing field data', function () {
+ $user = $this->actingAsUser();
+ $workspace = $this->createUserWorkspace($user);
+ $form = $this->createForm($user, $workspace);
+ $submissionData = attributionSubmissionData($this, $form);
+
+ $payload = AbstractIntegrationHandler::formatWebhookData(
+ $form,
+ $submissionData,
+ ['attribution' => ['utm_campaign' => 'launch']],
+ );
+
+ expect($payload['meta']['attribution'])->toBe(['utm_campaign' => 'launch'])
+ ->and($payload['data'])->not->toHaveKey('utm_campaign');
+});
diff --git a/api/tests/Feature/Zapier/IntegrationsTest.php b/api/tests/Feature/Zapier/IntegrationsTest.php
index 602446dfb..6bf2ed396 100644
--- a/api/tests/Feature/Zapier/IntegrationsTest.php
+++ b/api/tests/Feature/Zapier/IntegrationsTest.php
@@ -285,8 +285,12 @@ test('poll for the latest submission', function () {
// Create a submission for the form
$formData = $this->generateFormSubmissionData($form);
+ $attribution = ['utm_source' => 'zapier-poll'];
- $this->postJson(route('forms.answer', $form->slug), $formData)
+ $this->postJson(route('forms.answer', $form->slug), [
+ ...$formData,
+ 'tracking_parameters' => $attribution,
+ ])
->assertSuccessful()
->assertJson([
'type' => 'success',
@@ -315,6 +319,7 @@ test('poll for the latest submission', function () {
$receivedData = collect($responseData['data'])->values()->pluck('value')->toArray();
$this->assertEmpty(array_diff(array_values($formData), $receivedData));
+ $this->assertSame($attribution, $responseData['meta']['attribution']);
});
test('make up a submission when polling without any submission', function () {
diff --git a/client/components/open/forms/OpenCompleteForm.vue b/client/components/open/forms/OpenCompleteForm.vue
index 9bab58800..54700255e 100644
--- a/client/components/open/forms/OpenCompleteForm.vue
+++ b/client/components/open/forms/OpenCompleteForm.vue
@@ -213,7 +213,8 @@ if (props.form) {
formData: formDataRef,
formErrors: formErrorsRef,
formManager: formManager,
- darkMode: darkModeRef
+ darkMode: darkModeRef,
+ attribution: formManager.attribution,
})
}
@@ -250,7 +251,8 @@ watch(darkModeRef, (newDarkMode) => {
onMounted(() => {
if (isAutoSubmit.value && formManager) {
// Using nextTick to ensure form is fully rendered and initialized
- nextTick(() => {
+ nextTick(async () => {
+ await sdkBridge?.waitForHandshake?.()
triggerSubmit()
})
}
diff --git a/client/components/open/tables/OpenTable.vue b/client/components/open/tables/OpenTable.vue
index 1b1d13f95..2bb13415d 100644
--- a/client/components/open/tables/OpenTable.vue
+++ b/client/components/open/tables/OpenTable.vue
@@ -31,6 +31,7 @@
<TableColumnManager
class="ml-auto"
:table-state="tableState"
+ :data="filteredTableData"
/>
<UButton
@@ -528,4 +529,4 @@ watch(
)
useEventListener(window, 'resize', computeMaxHeight)
-</script>
\ No newline at end of file
+</script>
diff --git a/client/components/open/tables/components/TableColumnManager.vue b/client/components/open/tables/components/TableColumnManager.vue
index 8aa22f4f2..b615bf0e1 100644
--- a/client/components/open/tables/components/TableColumnManager.vue
+++ b/client/components/open/tables/components/TableColumnManager.vue
@@ -12,16 +12,14 @@
<template #content>
<div class="w-80 p-2 flex flex-col">
- <!-- Header -->
<div class="flex items-center justify-between">
<UInput
+ v-model="searchQuery"
variant="outline"
placeholder="Search columns..."
icon="i-heroicons-magnifying-glass"
size="sm"
- v-model="searchQuery"
/>
- <div class="flex items-center gap-1">
<UButton
size="sm"
variant="ghost"
@@ -30,25 +28,20 @@
@click="tableState.resetPreferences()"
/>
</div>
- </div>
- <!-- Column Sections -->
<ScrollableContainer class="mt-1">
<template v-for="section in columnSections" :key="section.type">
- <div
- v-if="section.columns.length > 0"
- class="flex flex-col"
- >
- <div class="flex items-center justify-between">
- <h4 class="text-xs text-neutral-500">{{ section.title }}</h4>
- <UButton
- size="xs"
- variant="link"
- :label="section.actionLabel"
- @click="toggleAllColumns(section.targetVisibility)"
- />
- </div>
-
+ <div v-if="section.columns.length > 0" class="flex flex-col">
+ <div class="flex items-center justify-between">
+ <h4 class="text-xs text-neutral-500">{{ section.title }}</h4>
+ <UButton
+ size="xs"
+ variant="link"
+ :label="section.actionLabel"
+ @click="setColumnsVisibility(section.columns, section.targetVisibility)"
+ />
+ </div>
+
<VueDraggable
:model-value="section.columns"
item-key="id"
@@ -60,80 +53,177 @@
@add="handleColumnAdd"
@update="handleColumnUpdate"
>
- <template #default>
- <div v-for="column in section.columns" :key="column.id" class="group">
- <div class="flex items-center gap-1 p-2 rounded-md hover:bg-neutral-50 transition-colors">
- <!-- Drag Handle -->
- <div class="w-4 h-4 flex items-center justify-center opacity-60 group-hover:opacity-100 transition-opacity">
- <UIcon name="clarity:drag-handle-line" class="h-6 w-6 -ml-1 shrink-0 text-neutral-400" />
- </div>
-
- <!-- Column Icon -->
- <div class="w-4 h-4 flex items-center justify-center">
- <BlockTypeIcon
- v-if="column.type"
- :type="column.type"
- bg-class="bg-transparent"
- text-class="text-neutral-600"
- class="flex-shrink-0"
- />
- </div>
-
- <!-- Column Name with Tooltip -->
- <UTooltip :text="column.header || column.id" :content="{ align: 'start' }">
- <span class="flex-1 text-sm truncate">
- {{ column.header || column.id }}
- </span>
- </UTooltip>
-
- <!-- Removed Indicator -->
- <UTooltip v-if="column.isRemoved" text="Column was removed from form" :content="{ align: 'end' }">
- <UIcon name="i-heroicons-trash" class="w-3 h-3 text-neutral-400" />
- </UTooltip>
-
- <!-- Column Actions -->
- <div class="flex items-center gap-1">
- <!-- Pin Toggle -->
- <UTooltip :text="getPinTooltip(column.id)">
- <UButton
- size="xs"
- :variant="columnPreferencesMap[column.id]?.pinned ? 'soft' : 'ghost'"
- :icon="getPinIcon(column.id)"
- :color="columnPreferencesMap[column.id]?.pinned ? 'primary' : 'neutral'"
- @click.prevent="tableState.toggleColumnPin(column.id)"
- />
- </UTooltip>
-
- <!-- Wrap Toggle -->
- <UTooltip :text="columnPreferencesMap[column.id]?.wrapped ? 'Disable text wrapping' : 'Enable text wrapping'">
- <UButton
- size="xs"
- :variant="columnPreferencesMap[column.id]?.wrapped ? 'soft' : 'ghost'"
- icon="i-ic-baseline-wrap-text"
- :color="columnPreferencesMap[column.id]?.wrapped ? 'primary' : 'neutral'"
- @click.prevent="tableState.toggleColumnWrapping(column.id)"
- />
- </UTooltip>
-
- <!-- Visibility Toggle Button -->
- <UTooltip :text="columnVisibilityMap[column.id] ? 'Hide' : 'Show'">
- <UButton
- size="xs"
- variant="ghost"
- color="neutral"
- :icon="columnVisibilityMap[column.id] ? 'i-heroicons-eye-solid' : 'i-heroicons-eye-slash-solid'"
- @click.prevent="props.tableState.toggleColumnVisibility(column.id)"
- />
- </UTooltip>
- </div>
- </div>
- </div>
- </template>
+ <TableColumnManagerRow
+ v-for="column in section.columns"
+ :key="column.id"
+ :column="column"
+ :table-state="tableState"
+ :preference="columnPreferencesMap[column.id]"
+ :visible="columnVisibilityMap[column.id]"
+ :display-name="columnDisplayName(column)"
+ :technical-name="columnTechnicalName(column)"
+ />
</VueDraggable>
+ </div>
+ </template>
+
+ <div
+ v-if="showAttributionGroup"
+ class="mt-2 pt-2 border-t border-neutral-200 dark:border-neutral-700"
+ >
+ <button
+ type="button"
+ class="w-full flex items-start gap-2 p-2 rounded-md text-left hover:bg-neutral-50 dark:hover:bg-neutral-800 transition-colors"
+ :aria-expanded="attributionGroupExpanded"
+ aria-controls="attribution-column-options"
+ @click="isAttributionExpanded = !isAttributionExpanded"
+ >
+ <UIcon name="i-lucide-chart-no-axes-combined" class="size-4 mt-0.5 text-neutral-500 shrink-0" />
+ <span class="flex-1 min-w-0">
+ <span class="flex items-center gap-2">
+ <span class="text-sm font-medium">Attribution &amp; tracking</span>
+ <UBadge
+ v-if="detectedAttributionCount > 0"
+ size="xs"
+ variant="soft"
+ color="neutral"
+ :label="`${detectedAttributionCount} on this page`"
+ />
+ </span>
+ <span class="block mt-0.5 text-xs text-neutral-500 leading-4">
+ Campaign parameters captured from form URLs
+ </span>
+ </span>
+ <UIcon
+ name="i-lucide-chevron-down"
+ class="size-4 mt-0.5 text-neutral-500 transition-transform"
+ :class="{ 'rotate-180': attributionGroupExpanded }"
+ />
+ </button>
+
+ <div v-if="attributionGroupExpanded" id="attribution-column-options" class="mt-1 pl-2">
+ <div
+ v-if="visibleAttributionColumns.length > 0"
+ class="flex items-center justify-between px-2 py-1"
+ >
+ <span class="text-xs text-neutral-500">
+ {{ visibleAttributionColumns.length }} shown in table
+ </span>
+ <UButton
+ size="xs"
+ variant="link"
+ color="neutral"
+ label="Hide URL parameters"
+ @click="setColumnsVisibility(visibleAttributionColumns, false)"
+ />
+ </div>
+
+ <div v-if="hiddenDetectedAttributionColumns.length > 0">
+ <div class="flex items-center justify-between px-2">
+ <h5 class="text-xs text-neutral-500">Detected on this page</h5>
+ <UButton
+ size="xs"
+ variant="link"
+ label="Show detected"
+ @click="setColumnsVisibility(hiddenDetectedAttributionColumns, true)"
+ />
+ </div>
+
+ <VueDraggable
+ :model-value="hiddenDetectedAttributionColumns"
+ item-key="id"
+ :ghost-class="['opacity-50', 'bg-blue-50', 'rounded-md']"
+ :chosen-class="['bg-blue-100', 'rounded-md']"
+ :animation="200"
+ group="columns"
+ data-section-type="hidden"
+ @add="handleColumnAdd"
+ @update="handleColumnUpdate"
+ >
+ <TableColumnManagerRow
+ v-for="column in hiddenDetectedAttributionColumns"
+ :key="column.id"
+ :column="column"
+ :table-state="tableState"
+ :preference="columnPreferencesMap[column.id]"
+ :visible="false"
+ :display-name="columnDisplayName(column)"
+ :technical-name="columnTechnicalName(column)"
+ />
+ </VueDraggable>
+ </div>
+
+ <p
+ v-else-if="detectedAttributionCount > 0 && !normalizedSearchQuery"
+ class="px-2 py-1 text-xs text-neutral-500"
+ >
+ All detected parameters are shown in the table.
+ </p>
+
+ <div v-if="hiddenOtherAttributionColumns.length > 0" class="mt-1">
+ <button
+ type="button"
+ class="w-full flex items-center gap-2 px-2 py-1.5 rounded-md text-left hover:bg-neutral-50 dark:hover:bg-neutral-800 transition-colors"
+ :aria-expanded="otherAttributionExpanded"
+ aria-controls="other-attribution-column-options"
+ @click="isOtherAttributionExpanded = !isOtherAttributionExpanded"
+ >
+ <UIcon
+ name="i-lucide-chevron-right"
+ class="size-3.5 text-neutral-500 transition-transform"
+ :class="{ 'rotate-90': otherAttributionExpanded }"
+ />
+ <span class="flex-1 text-xs font-medium text-neutral-600 dark:text-neutral-300">
+ Other supported parameters
+ </span>
+ <span class="text-xs text-neutral-500">{{ hiddenOtherAttributionColumns.length }}</span>
+ </button>
+
+ <div v-if="otherAttributionExpanded" id="other-attribution-column-options">
+ <div class="flex justify-end px-2">
+ <UButton
+ size="xs"
+ variant="link"
+ label="Show all"
+ @click="setColumnsVisibility(hiddenOtherAttributionColumns, true)"
+ />
+ </div>
+
+ <VueDraggable
+ :model-value="hiddenOtherAttributionColumns"
+ item-key="id"
+ :ghost-class="['opacity-50', 'bg-blue-50', 'rounded-md']"
+ :chosen-class="['bg-blue-100', 'rounded-md']"
+ :animation="200"
+ group="columns"
+ data-section-type="hidden"
+ @add="handleColumnAdd"
+ @update="handleColumnUpdate"
+ >
+ <TableColumnManagerRow
+ v-for="column in hiddenOtherAttributionColumns"
+ :key="column.id"
+ :column="column"
+ :table-state="tableState"
+ :preference="columnPreferencesMap[column.id]"
+ :visible="false"
+ :display-name="columnDisplayName(column)"
+ :technical-name="columnTechnicalName(column)"
+ />
+ </VueDraggable>
+ </div>
+ </div>
+ </div>
</div>
- </template>
+
+ <p
+ v-if="filteredColumns.length === 0 && !showAttributionGroup"
+ class="px-2 py-4 text-center text-sm text-neutral-500"
+ >
+ No columns found.
+ </p>
</ScrollableContainer>
- <div class="w-full h-1"></div>
+ <div class="w-full h-1" />
</div>
</template>
</UPopover>
@@ -142,14 +232,24 @@
<script setup>
import { VueDraggable } from 'vue-draggable-plus'
-import BlockTypeIcon from '~/components/open/forms/components/BlockTypeIcon.vue'
import ScrollableContainer from '~/components/dashboard/ScrollableContainer.vue'
+import TableColumnManagerRow from './TableColumnManagerRow.vue'
+import {
+ ATTRIBUTION_PARAMETER_LABELS,
+ attributionParameterFromColumnId,
+ detectedAttributionParameters,
+ isColumnVisibilityTransition,
+} from '~/lib/forms/submissionAttribution'
const props = defineProps({
tableState: {
type: Object,
required: true,
},
+ data: {
+ type: Array,
+ default: () => [],
+ },
popoverContent: {
type: Object,
default: () => ({
@@ -159,17 +259,18 @@ const props = defineProps({
},
})
-
-
const isPopoverOpen = ref(false)
const searchQuery = ref('')
+const isAttributionExpanded = ref(false)
+const isOtherAttributionExpanded = ref(false)
+
+const normalizedSearchQuery = computed(() => searchQuery.value.trim().toLowerCase())
-// Computed maps for better performance - avoid repeated function calls in templates
const columnVisibilityMap = computed(() => {
const map = {}
const visibility = props.tableState.columnVisibility.value || {}
const columns = props.tableState.orderedColumns.value || []
-
+
columns.forEach(column => {
map[column.id] = visibility[column.id] !== false
})
@@ -179,70 +280,107 @@ const columnVisibilityMap = computed(() => {
const columnPreferencesMap = computed(() => {
const map = {}
const columns = props.tableState.orderedColumns.value || []
-
+
columns.forEach(column => {
map[column.id] = props.tableState.getColumnPreference(column.id)
})
return map
})
+const columnAttributionParameter = column => attributionParameterFromColumnId(column.id)
+const isAttributionColumn = column => columnAttributionParameter(column) !== null
+
+const columnDisplayName = (column) => {
+ const parameter = columnAttributionParameter(column)
+ return parameter ? ATTRIBUTION_PARAMETER_LABELS[parameter] : (column.header || column.id)
+}
+
+const columnTechnicalName = (column) => columnAttributionParameter(column) || ''
+
+const columnMatchesQuery = (column) => {
+ if (!normalizedSearchQuery.value) return true
+ return [column.id, column.header, columnDisplayName(column)]
+ .filter(Boolean)
+ .some(value => String(value).toLowerCase().includes(normalizedSearchQuery.value))
+}
-// Filter columns based on search query and maintain order
const filteredColumns = computed(() => {
const columns = props.tableState.orderedColumns.value || []
if (!Array.isArray(columns)) return []
-
- const query = searchQuery.value.toLowerCase()
- return columns.filter(column =>
- column.id !== 'actions' &&
- (column.header || column.id).toLowerCase().includes(query)
- )
-})
-// Computed visible columns (reactive to table state) - now using the map
-const visibleColumns = computed(() => {
- const visibilityMap = columnVisibilityMap.value
- return filteredColumns.value.filter(column => visibilityMap[column.id] !== false)
+ return columns.filter(column => column.id !== 'actions' && columnMatchesQuery(column))
})
-// Computed hidden columns (reactive to table state) - now using the map
-const hiddenColumns = computed(() => {
- const visibilityMap = columnVisibilityMap.value
- return filteredColumns.value.filter(column => visibilityMap[column.id] === false)
-})
+const attributionColumns = computed(() => {
+ const columns = props.tableState.orderedColumns.value || []
+ if (!Array.isArray(columns)) return []
-// Column sections configuration (now fully reactive)
-const columnSections = computed(() => {
- return [
- {
- type: 'visible',
- title: 'Shown in table',
- actionLabel: 'Hide All',
- targetVisibility: false,
- columns: visibleColumns.value
- },
- {
- type: 'hidden',
- title: 'Hidden in table',
- actionLabel: 'Show All',
- targetVisibility: true,
- columns: hiddenColumns.value
- }
- ]
+ return columns.filter(column => column.id !== 'actions' && isAttributionColumn(column))
})
-// Handle drag end event
+const visibleColumns = computed(() => filteredColumns.value.filter(column => (
+ columnVisibilityMap.value[column.id] !== false
+)))
+
+const hiddenColumns = computed(() => filteredColumns.value.filter(column => (
+ columnVisibilityMap.value[column.id] === false && !isAttributionColumn(column)
+)))
+
+const hiddenAttributionColumns = computed(() => filteredColumns.value.filter(column => (
+ columnVisibilityMap.value[column.id] === false && isAttributionColumn(column)
+)))
+
+const visibleAttributionColumns = computed(() => attributionColumns.value.filter(column => (
+ columnVisibilityMap.value[column.id] !== false
+)))
+
+const detectedAttributionParameterSet = computed(() => new Set(detectedAttributionParameters(props.data)))
+const detectedAttributionCount = computed(() => detectedAttributionParameterSet.value.size)
+
+const hiddenDetectedAttributionColumns = computed(() => hiddenAttributionColumns.value.filter(column => (
+ detectedAttributionParameterSet.value.has(columnAttributionParameter(column))
+)))
+
+const hiddenOtherAttributionColumns = computed(() => hiddenAttributionColumns.value.filter(column => (
+ !detectedAttributionParameterSet.value.has(columnAttributionParameter(column))
+)))
+
+const showAttributionGroup = computed(() => filteredColumns.value.some(isAttributionColumn))
+const attributionGroupExpanded = computed(() => isAttributionExpanded.value || normalizedSearchQuery.value.length > 0)
+const otherAttributionExpanded = computed(() => isOtherAttributionExpanded.value || normalizedSearchQuery.value.length > 0)
+
+const columnSections = computed(() => [
+ {
+ type: 'visible',
+ title: 'Shown in table',
+ actionLabel: 'Hide All',
+ targetVisibility: false,
+ columns: visibleColumns.value,
+ },
+ {
+ type: 'hidden',
+ title: 'Hidden in table',
+ actionLabel: 'Show All',
+ targetVisibility: true,
+ columns: hiddenColumns.value,
+ },
+])
+
const handleColumnAdd = async (evt) => {
const column = evt.data || evt.clonedData
if (!column) return
- const isVisibleTarget = evt.to?.dataset?.sectionType === 'visible'
+
+ const sourceSectionType = evt.from?.dataset?.sectionType
+ const targetSectionType = evt.to?.dataset?.sectionType
+ if (!isColumnVisibilityTransition(sourceSectionType, targetSectionType)) return
+
+ const isVisibleTarget = targetSectionType === 'visible'
if (isVisibleTarget) {
props.tableState.toggleColumnVisibility(column.id)
await nextTick()
props.tableState.setColumnOrder(column.id, evt.newIndex)
} else {
- // Moved into hidden
props.tableState.toggleColumnVisibility(column.id)
}
}
@@ -253,40 +391,11 @@ const handleColumnUpdate = (evt) => {
props.tableState.setColumnOrder(column.id, evt.newIndex)
}
-// Get pin icon - now using computed map
-const getPinIcon = (columnId) => {
- const pref = columnPreferencesMap.value[columnId]
- return pref?.pinned === 'left' ? 'i-ic-baseline-push-pin' : 'i-ic-baseline-push-pin'
-}
-
-// Get pin tooltip - now using computed map
-const getPinTooltip = (columnId) => {
- const pref = columnPreferencesMap.value[columnId]
- return pref?.pinned === 'left' ? 'Unpin column' : 'Pin column to left'
-}
-
-// Toggle all columns visibility - now using computed map
-const toggleAllColumns = (targetVisibility) => {
- const columns = props.tableState.orderedColumns.value || []
- const visibilityMap = columnVisibilityMap.value
-
- columns
- .filter(column => column.id !== 'actions')
- .forEach(column => {
- if ((visibilityMap[column.id] !== false) !== targetVisibility) {
- props.tableState.toggleColumnVisibility(column.id)
- }
- })
+const setColumnsVisibility = (columns, targetVisibility) => {
+ columns.forEach(column => {
+ if ((columnVisibilityMap.value[column.id] !== false) !== targetVisibility) {
+ props.tableState.toggleColumnVisibility(column.id)
+ }
+ })
}
</script>
-
-<style scoped>
-/* Ensure drag cursor is applied to the entire row */
-.group {
- cursor: grab;
-}
-
-.group:active {
- cursor: grabbing;
-}
-</style>
diff --git a/client/components/open/tables/components/TableColumnManagerRow.vue b/client/components/open/tables/components/TableColumnManagerRow.vue
new file mode 100644
index 000000000..cb17a1415
--- /dev/null
+++ b/client/components/open/tables/components/TableColumnManagerRow.vue
@@ -0,0 +1,112 @@
+<template>
+ <div class="group">
+ <div class="flex items-center gap-1 p-2 rounded-md hover:bg-neutral-50 transition-colors">
+ <div class="w-4 h-4 flex items-center justify-center opacity-60 group-hover:opacity-100 transition-opacity">
+ <UIcon name="clarity:drag-handle-line" class="h-6 w-6 -ml-1 shrink-0 text-neutral-400" />
+ </div>
+
+ <div class="w-4 h-4 flex items-center justify-center">
+ <BlockTypeIcon
+ v-if="column.type"
+ :type="column.type"
+ bg-class="bg-transparent"
+ text-class="text-neutral-600"
+ class="flex-shrink-0"
+ />
+ </div>
+
+ <UTooltip :text="technicalName || displayName" :content="{ align: 'start' }">
+ <div class="flex-1 min-w-0">
+ <div class="text-sm truncate">{{ displayName }}</div>
+ <div v-if="technicalName" class="text-xs text-neutral-500 truncate">
+ {{ technicalName }}
+ </div>
+ </div>
+ </UTooltip>
+
+ <UTooltip v-if="column.isRemoved" text="Column was removed from form" :content="{ align: 'end' }">
+ <UIcon name="i-heroicons-trash" class="w-3 h-3 text-neutral-400" />
+ </UTooltip>
+
+ <div class="flex items-center gap-1">
+ <UTooltip :text="pinLabel">
+ <UButton
+ size="xs"
+ :variant="preference?.pinned ? 'soft' : 'ghost'"
+ icon="i-ic-baseline-push-pin"
+ :color="preference?.pinned ? 'primary' : 'neutral'"
+ :aria-label="`${pinLabel}: ${displayName}`"
+ @click.prevent="tableState.toggleColumnPin(column.id)"
+ />
+ </UTooltip>
+
+ <UTooltip :text="wrapLabel">
+ <UButton
+ size="xs"
+ :variant="preference?.wrapped ? 'soft' : 'ghost'"
+ icon="i-ic-baseline-wrap-text"
+ :color="preference?.wrapped ? 'primary' : 'neutral'"
+ :aria-label="`${wrapLabel}: ${displayName}`"
+ @click.prevent="tableState.toggleColumnWrapping(column.id)"
+ />
+ </UTooltip>
+
+ <UTooltip :text="visibilityLabel">
+ <UButton
+ size="xs"
+ variant="ghost"
+ color="neutral"
+ :icon="visible ? 'i-heroicons-eye-solid' : 'i-heroicons-eye-slash-solid'"
+ :aria-label="`${visibilityLabel}: ${displayName}`"
+ @click.prevent="tableState.toggleColumnVisibility(column.id)"
+ />
+ </UTooltip>
+ </div>
+ </div>
+ </div>
+</template>
+
+<script setup>
+import BlockTypeIcon from '~/components/open/forms/components/BlockTypeIcon.vue'
+
+const props = defineProps({
+ column: {
+ type: Object,
+ required: true,
+ },
+ tableState: {
+ type: Object,
+ required: true,
+ },
+ preference: {
+ type: Object,
+ default: () => ({}),
+ },
+ visible: {
+ type: Boolean,
+ default: true,
+ },
+ displayName: {
+ type: String,
+ required: true,
+ },
+ technicalName: {
+ type: String,
+ default: '',
+ },
+})
+
+const pinLabel = computed(() => props.preference?.pinned === 'left' ? 'Unpin column' : 'Pin column to left')
+const wrapLabel = computed(() => props.preference?.wrapped ? 'Disable text wrapping' : 'Enable text wrapping')
+const visibilityLabel = computed(() => props.visible ? 'Hide column' : 'Show column')
+</script>
+
+<style scoped>
+.group {
+ cursor: grab;
+}
+
+.group:active {
+ cursor: grabbing;
+}
+</style>
diff --git a/client/composables/components/tables/useTableState.js b/client/composables/components/tables/useTableState.js
index 391e1eb12..8f3c95e4e 100644
--- a/client/composables/components/tables/useTableState.js
+++ b/client/composables/components/tables/useTableState.js
@@ -1,6 +1,11 @@
import { computed } from 'vue'
import { useTableColumnPreferences } from './useTableColumnPreferences'
import debounce from 'debounce'
+import {
+ ATTRIBUTION_PARAMETERS,
+ attributionColumnAccessor,
+ attributionColumnId,
+} from '~/lib/forms/submissionAttribution'
const normalizeColumnList = (columns) => {
if (Array.isArray(columns)) {
@@ -86,6 +91,20 @@ export function useTableState(form, withActions = false) {
})
}
+ ATTRIBUTION_PARAMETERS.forEach((parameter) => {
+ const columnId = attributionColumnId(parameter)
+ baseColumns.push({
+ id: columnId,
+ accessorFn: attributionColumnAccessor(parameter),
+ header: parameter,
+ type: 'text',
+ hiddenByDefault: true,
+ enableResizing: true,
+ minSize: 100,
+ maxSize: 500,
+ })
+ })
+
if (hasFeature('enable_partial_submissions') && (form.value?.enable_partial_submissions ?? false)) {
if (!baseColumns.find(property => property.id === 'status')) {
baseColumns.push({
@@ -136,8 +155,10 @@ export function useTableState(form, withActions = false) {
const configCols = columnConfigurations.value || []
configCols.forEach(col => {
const pref = prefs.columns[col.id] || {}
- // Use preference if set, otherwise default: visible for regular columns, hidden for removed columns
- const visible = pref.visible !== null && pref.visible !== undefined ? pref.visible : !col.isRemoved
+ // Use preference if set, otherwise hide removed and system-hidden columns.
+ const visible = pref.visible !== null && pref.visible !== undefined
+ ? pref.visible
+ : !col.isRemoved && !col.hiddenByDefault
visibility[col.id] = visible
})
return visibility
@@ -145,9 +166,10 @@ export function useTableState(form, withActions = false) {
set(newVisibility) {
Object.entries(newVisibility).forEach(([columnId, visible]) => {
const pref = getColumnPreference(columnId)
+ const column = columnConfigurations.value.find(candidate => candidate.id === columnId)
const currentVisible = pref.visible !== null && pref.visible !== undefined
? pref.visible
- : !columnConfigurations.value.find(c => c.id === columnId)?.isRemoved
+ : !column?.isRemoved && !column?.hiddenByDefault
if (currentVisible !== visible) {
setColumnPreference(columnId, { visible })
}
diff --git a/client/composables/forms/usePartialSubmission.js b/client/composables/forms/usePartialSubmission.js
index ad966fdb6..de352d1c6 100644
--- a/client/composables/forms/usePartialSubmission.js
+++ b/client/composables/forms/usePartialSubmission.js
@@ -12,7 +12,7 @@ const submissionHashes = ref(new Map())
* @param {import('vue').ComputedRef<Object>} formDataRef - Computed reference to the reactive form data.
* @param {Object} pendingSubmissionService - The instantiated service from usePendingSubmission.
*/
-export function usePartialSubmission(formConfig, formDataRef, pendingSubmissionService) {
+export function usePartialSubmission(formConfig, formDataRef, pendingSubmissionService, attribution = null) {
let syncTimeout = null
let dataWatcher = null
@@ -87,7 +87,10 @@ export function usePartialSubmission(formConfig, formDataRef, pendingSubmissionS
const response = await formsApi.submissions.answer(config.slug, {
...currentData,
'is_partial': true,
- 'submission_hash': getSubmissionHash() // Use the updated getter
+ 'submission_hash': getSubmissionHash(), // Use the updated getter
+ ...(Object.keys(toValue(attribution) || {}).length > 0
+ ? { tracking_parameters: toValue(attribution) }
+ : {}),
})
if (response.submission_hash) {
setSubmissionHash(response.submission_hash) // Use the updated setter
@@ -190,4 +193,4 @@ export function usePartialSubmission(formConfig, formDataRef, pendingSubmissionS
setSubmissionHash, // Use the setter that updates both
clearSubmissionHash // Clear hash from both localStorage and memory after successful submission
}
-}
\ No newline at end of file
+}
diff --git a/client/composables/query/forms/useFormSubmissions.js b/client/composables/query/forms/useFormSubmissions.js
index 236c56304..211edf769 100644
--- a/client/composables/query/forms/useFormSubmissions.js
+++ b/client/composables/query/forms/useFormSubmissions.js
@@ -1,5 +1,19 @@
import { useQueryClient, useQuery, useMutation, keepPreviousData } from '@tanstack/vue-query'
import { formsApi } from '~/api/forms'
+import { attributionColumnId } from '~/lib/forms/submissionAttribution'
+
+const tableSubmission = (record) => {
+ const attribution = record?.meta?.attribution || {}
+ const attributionColumns = Object.entries(attribution).reduce((columns, [parameter, value]) => {
+ columns[attributionColumnId(parameter)] = value
+ return columns
+ }, {})
+
+ return {
+ ...record.data,
+ ...attributionColumns,
+ }
+}
export function useFormSubmissions() {
const queryClient = useQueryClient()
@@ -80,7 +94,7 @@ export function useFormSubmissions() {
// Computed properties
const submissions = computed(() =>
- query.data.value?.data?.map(record => record.data) || []
+ query.data.value?.data?.map(tableSubmission) || []
)
const pagination = computed(() => query.data.value?.meta || null)
@@ -253,4 +267,4 @@ export function useFormSubmissions() {
invalidateSubmissions,
invalidateSubmission,
}
-}
\ No newline at end of file
+}
diff --git a/client/lib/forms/composables/useFormManager.js b/client/lib/forms/composables/useFormManager.js
index 15422e61e..720e08236 100644
--- a/client/lib/forms/composables/useFormManager.js
+++ b/client/lib/forms/composables/useFormManager.js
@@ -16,6 +16,7 @@ import { useConfetti } from '~/composables/useConfetti'
import { cloneDeep } from 'lodash'
import { useFieldState } from './useFieldState'
import { useComputedVariables } from '~/composables/forms/useComputedVariables'
+import { useSubmissionAttribution } from './useSubmissionAttribution'
/**
* @fileoverview Main orchestrator composable for form operations.
@@ -49,6 +50,7 @@ export function useFormManager(initialFormConfig, initialMode = FormMode.LIVE, o
// Create a reactive reference to the form data for dependent composables to watch
const formDataRef = computed(() => form.data())
const computedVariables = useComputedVariables(computed(() => config.value), formDataRef)
+ const submissionAttribution = useSubmissionAttribution()
// Centralized field state (single instance per manager)
const fieldState = useFieldState(
@@ -62,7 +64,12 @@ export function useFormManager(initialFormConfig, initialMode = FormMode.LIVE, o
const pendingSubmissionService = usePendingSubmission(config, formDataRef)
// Instantiate partial submission service (handles server auto-sync)
- const partialSubmissionService = usePartialSubmission(config, formDataRef, pendingSubmissionService)
+ const partialSubmissionService = usePartialSubmission(
+ config,
+ formDataRef,
+ pendingSubmissionService,
+ submissionAttribution.attribution,
+ )
// --- Instantiate Other Composables (Services) ---
const timer = useFormTimer(pendingSubmissionService)
@@ -95,7 +102,7 @@ export function useFormManager(initialFormConfig, initialMode = FormMode.LIVE, o
const validation = useFormValidation(config, form, state)
const payment = useFormPayment(config, form)
- const submission = useFormSubmission(config, form)
+ const submission = useFormSubmission(config, form, submissionAttribution.attribution)
/**
* Updates the form configuration when the entire form reference changes.
@@ -125,6 +132,7 @@ export function useFormManager(initialFormConfig, initialMode = FormMode.LIVE, o
state.isProcessing = true
state.isSubmitted = false
state.currentPage = 0
+ submissionAttribution.captureIframeAttribution(options.urlParams)
const initializationPromise = initialization.initialize({
...options
@@ -336,7 +344,10 @@ export function useFormManager(initialFormConfig, initialMode = FormMode.LIVE, o
: null
},
submission_data: form.data(),
- completion_time: completionTime
+ completion_time: completionTime,
+ ...(Object.keys(submissionAttribution.attribution.value).length > 0
+ ? { meta: { attribution: submissionAttribution.attribution.value } }
+ : {}),
})
// Send message to parent if in iframe
@@ -410,6 +421,8 @@ export function useFormManager(initialFormConfig, initialMode = FormMode.LIVE, o
strategy, // Current mode strategy (computed)
pendingSubmission: pendingSubmissionService, // Expose pendingSubmission service
partialSubmission: partialSubmissionService, // Expose partialSubmission service with debounced sync
+ attribution: submissionAttribution.attribution,
+ mergeParentAttribution: submissionAttribution.mergeParentAttribution,
// UI-related properties
darkMode, // Dark mode setting
diff --git a/client/lib/forms/composables/useFormSubmission.js b/client/lib/forms/composables/useFormSubmission.js
index ea9a82b8e..e03ab8587 100644
--- a/client/lib/forms/composables/useFormSubmission.js
+++ b/client/lib/forms/composables/useFormSubmission.js
@@ -3,7 +3,7 @@ import { toValue } from 'vue'
/**
* @fileoverview Composable for handling the final form submission process.
*/
-export function useFormSubmission(formConfig, form) {
+export function useFormSubmission(formConfig, form, attribution = null) {
/**
* Prepares additional metadata for the submission payload.
@@ -34,6 +34,11 @@ export function useFormSubmission(formConfig, form) {
metadata.submission_id = options.submissionId
}
+ const trackingParameters = toValue(attribution)
+ if (trackingParameters && Object.keys(trackingParameters).length > 0) {
+ metadata.tracking_parameters = trackingParameters
+ }
+
return metadata
}
diff --git a/client/lib/forms/composables/useSubmissionAttribution.js b/client/lib/forms/composables/useSubmissionAttribution.js
new file mode 100644
index 000000000..5b0cb1420
--- /dev/null
+++ b/client/lib/forms/composables/useSubmissionAttribution.js
@@ -0,0 +1,37 @@
+import { computed, ref } from 'vue'
+import {
+ extractAttribution,
+ mergeAttribution,
+ sanitizeAttribution,
+} from '~/lib/forms/submissionAttribution'
+
+export function useSubmissionAttribution() {
+ const iframeAttribution = ref({})
+ const parentAttribution = ref({})
+ let iframeAttributionCaptured = false
+
+ const attribution = computed(() => mergeAttribution(
+ iframeAttribution.value,
+ parentAttribution.value,
+ ))
+
+ const captureIframeAttribution = (searchParams) => {
+ if (iframeAttributionCaptured) return
+
+ iframeAttribution.value = extractAttribution(searchParams)
+ iframeAttributionCaptured = true
+ }
+
+ const mergeParentAttribution = (parameters) => {
+ parentAttribution.value = {
+ ...parentAttribution.value,
+ ...sanitizeAttribution(parameters),
+ }
+ }
+
+ return {
+ attribution,
+ captureIframeAttribution,
+ mergeParentAttribution,
+ }
+}
diff --git a/client/lib/forms/submissionAttribution.js b/client/lib/forms/submissionAttribution.js
new file mode 100644
index 000000000..e53182668
--- /dev/null
+++ b/client/lib/forms/submissionAttribution.js
@@ -0,0 +1,112 @@
+export const ATTRIBUTION_MAX_VALUE_LENGTH = 2048
+
+export const ATTRIBUTION_PARAMETERS = Object.freeze([
+ 'utm_source',
+ 'utm_medium',
+ 'utm_campaign',
+ 'utm_id',
+ 'utm_term',
+ 'utm_content',
+ 'utm_source_platform',
+ 'utm_creative_format',
+ 'utm_marketing_tactic',
+ 'gclid',
+ 'gbraid',
+ 'wbraid',
+ 'dclid',
+ 'fbclid',
+ 'ttclid',
+ 'msclkid',
+])
+
+export const ATTRIBUTION_PARAMETER_LABELS = Object.freeze({
+ utm_source: 'Source',
+ utm_medium: 'Medium',
+ utm_campaign: 'Campaign',
+ utm_id: 'Campaign ID',
+ utm_term: 'Search term',
+ utm_content: 'Content',
+ utm_source_platform: 'Source platform',
+ utm_creative_format: 'Creative format',
+ utm_marketing_tactic: 'Marketing tactic',
+ gclid: 'Google Click ID',
+ gbraid: 'Google GBRAID',
+ wbraid: 'Google WBRAID',
+ dclid: 'Google Display Click ID',
+ fbclid: 'Meta Click ID',
+ ttclid: 'TikTok Click ID',
+ msclkid: 'Microsoft Ads Click ID',
+})
+
+export function attributionColumnId(parameter) {
+ return `meta.attribution.${parameter}`
+}
+
+export function attributionColumnAccessor(parameter) {
+ return row => row?.[attributionColumnId(parameter)]
+}
+
+export function attributionParameterFromColumnId(columnId) {
+ const prefix = 'meta.attribution.'
+ if (typeof columnId !== 'string' || !columnId.startsWith(prefix)) return null
+
+ const parameter = columnId.slice(prefix.length)
+ return ATTRIBUTION_PARAMETERS.includes(parameter) ? parameter : null
+}
+
+export function detectedAttributionParameters(rows) {
+ if (!Array.isArray(rows)) return []
+
+ return ATTRIBUTION_PARAMETERS.filter(parameter => rows.some((row) => {
+ const value = row?.[attributionColumnId(parameter)]
+ return value !== undefined && value !== null && value !== ''
+ }))
+}
+
+export function isColumnVisibilityTransition(fromSectionType, toSectionType) {
+ return ['visible', 'hidden'].includes(fromSectionType)
+ && ['visible', 'hidden'].includes(toSectionType)
+ && fromSectionType !== toSectionType
+}
+
+export function sanitizeAttribution(parameters) {
+ if (!parameters || typeof parameters !== 'object' || Array.isArray(parameters)) return {}
+
+ return ATTRIBUTION_PARAMETERS.reduce((attribution, parameter) => {
+ const value = parameters[parameter]
+ if (typeof value !== 'string' || value.trim() === '' || value.length > ATTRIBUTION_MAX_VALUE_LENGTH) {
+ return attribution
+ }
+
+ attribution[parameter] = value
+ return attribution
+ }, {})
+}
+
+export function extractAttribution(searchParams) {
+ let params
+ try {
+ params = searchParams instanceof URLSearchParams
+ ? searchParams
+ : new URLSearchParams(searchParams || '')
+ } catch {
+ return {}
+ }
+
+ return ATTRIBUTION_PARAMETERS.reduce((attribution, parameter) => {
+ const value = params.getAll(parameter).find(candidate => (
+ candidate.trim() !== '' && candidate.length <= ATTRIBUTION_MAX_VALUE_LENGTH
+ ))
+
+ if (value !== undefined) attribution[parameter] = value
+
+ return attribution
+ }, {})
+}
+
+export function mergeAttribution(iframeAttribution, parentAttribution) {
+ return {
+ ...sanitizeAttribution(parentAttribution),
+ ...sanitizeAttribution(iframeAttribution),
+ }
+}
diff --git a/client/lib/sdk/sdkBridgeMessaging.js b/client/lib/sdk/sdkBridgeMessaging.js
index 871f26430..a77baa605 100644
--- a/client/lib/sdk/sdkBridgeMessaging.js
+++ b/client/lib/sdk/sdkBridgeMessaging.js
@@ -1,3 +1,5 @@
+import { sanitizeAttribution } from '../forms/submissionAttribution'
+
export const MSG_PREFIX = 'opnform:'
export const WILDCARD_ORIGIN = '*'
@@ -49,6 +51,7 @@ export function createSdkBridgeMessageHandler(options) {
initialTrustedOrigin = null,
postToParent,
onCommand,
+ onHandshake,
} = options
let trustedOrigin = initialTrustedOrigin
@@ -108,6 +111,7 @@ export function createSdkBridgeMessageHandler(options) {
}
sdkToken = sdkToken || incomingToken
+ onHandshake?.(sanitizeAttribution(message.trackingParameters))
sendHandshakeAck(true)
}
diff --git a/client/lib/sdk/useSdkBridge.js b/client/lib/sdk/useSdkBridge.js
index 2b8cca9a4..3a45c6cab 100644
--- a/client/lib/sdk/useSdkBridge.js
+++ b/client/lib/sdk/useSdkBridge.js
@@ -686,11 +686,19 @@ export function useSdkBridge(options) {
formData,
formErrors,
formManager,
- darkMode
+ darkMode,
+ attribution,
} = options
const isIframe = useIsIframe()
let messageHandler = null
+ let handshakeReceived = !isIframe
+ let resolveHandshake = null
+ const handshakePromise = handshakeReceived
+ ? Promise.resolve()
+ : new Promise((resolve) => {
+ resolveHandshake = resolve
+ })
const initialSdkToken = typeof window !== 'undefined' ? readSdkTokenFromUrl() : null
const initialTrustedOrigin = typeof window !== 'undefined'
@@ -916,8 +924,26 @@ export function useSdkBridge(options) {
postMessageSafe(window.parent, message, origin)
},
onCommand: handleCommand,
+ onHandshake: (trackingParameters) => {
+ formManager?.mergeParentAttribution?.(trackingParameters)
+ handshakeReceived = true
+ resolveHandshake?.()
+ resolveHandshake = null
+ },
})
+ function waitForHandshake(timeoutMs = 3000) {
+ if (!import.meta.client || handshakeReceived) return Promise.resolve()
+
+ return new Promise((resolve) => {
+ const timeoutId = setTimeout(resolve, timeoutMs)
+ handshakePromise.then(() => {
+ clearTimeout(timeoutId)
+ resolve()
+ })
+ })
+ }
+
/**
* Handle incoming messages
*/
@@ -1023,10 +1049,14 @@ export function useSdkBridge(options) {
}
function onSubmitSuccess(submissionData) {
+ const trackingParameters = toValue(attribution) || {}
emitEvent(EVENTS.SUBMIT, {
data: submissionData.data || toValue(formData),
submissionId: submissionData.submissionId,
- completionTime: submissionData.completionTime
+ completionTime: submissionData.completionTime,
+ ...(Object.keys(trackingParameters).length > 0
+ ? { meta: { attribution: trackingParameters } }
+ : {}),
})
}
@@ -1077,6 +1107,7 @@ export function useSdkBridge(options) {
onSubmitSuccess,
onSubmitError,
onReset,
+ waitForHandshake,
EVENTS
}
}
diff --git a/client/public/widgets/embed-min.js b/client/public/widgets/embed-min.js
index 5498c6206..b25b3855b 100644
--- a/client/public/widgets/embed-min.js
+++ b/client/public/widgets/embed-min.js
@@ -12,11 +12,24 @@
".nf-main {\n position: fixed;\n width: 100%;\n height: 100vh;\n top: 0px;\n bottom: 0px;\n left: 0px;\n right: 0px;\n z-index: 500;\n pointer-events: none;\n }\n .nf-main .nf-emoji {\n pointer-events: auto;\n width:60px;\n height: 60px;\n display: flex;\n align-items:center;\n justify-content:center;\n text-align: center;\n background-color: #3B82F6;\n padding: 8px 10px;\n border: none;\n cursor: pointer;\n position: fixed;\n bottom: 23px;\n right: 28px;\n border-radius: 100%;\n z-index: 999\n }\n .nf-main.nf-left .nf-emoji{\n left: 28px !important;\n right: inherit !important\n }\n .nf-main .nf-emoji .nf-emoji-icon, .nf-main .nf-emoji .nf-emoji-icon-close{\n font-size: 30px;\n color:white;\n }\n .nf-main .nf-emoji .nf-emoji-icon-close {\n display: none;\n }\n .nf-main.open .nf-emoji .nf-emoji-icon{\n display: none !important\n }\n .nf-main.open .nf-emoji .nf-emoji-icon-close{\n display: block !important\n }\n .nf-main .nf-popup {\n\n display: flex;\n align-items: end;\n flex-direction: column-reverse;\n align-content: flex-end;\n padding: 20px;\n padding-bottom: 100px;\n width: 100%;\n height: 100vh;\n visibility: hidden;\n opacity:0; transition:\n opacity 0.2s, 0.2s ease-in-out;\n transform: translateY(30px);\n }\n .nf-main.open .nf-popup {\n visibility: visible !important;\n opacity: 1;\n transform: translateY(0px);\n }\n .nf-main .nf-popup iframe {\n width: 100%;\n pointer-events: auto;\n z-index: 999!important;\n bottom: 100px;\n right: 20px;\n height: 450px;\n background: #fff;\n border-radius: 12px;\n box-shadow: 0 6px 6px 0 rgba(0,0,0,.02),0 8px 24px 0 rgba(0,0,0,.12)!important\n }\n .nf-main.nf-left .nf-popup {\n align-items: start !important;\n }",
),
(function () {
+ const u = [
+ "utm_source", "utm_medium", "utm_campaign", "utm_id", "utm_term", "utm_content",
+ "utm_source_platform", "utm_creative_format", "utm_marketing_tactic",
+ "gclid", "gbraid", "wbraid", "dclid", "fbclid", "ttclid", "msclkid",
+ ]
const n = JSON.parse(document.currentScript.getAttribute("data-nf"))
let e = n?.formurl || null
if (window.location !== window.parent.location || window.frameElement || !e)
return !1
- e = e + (e.indexOf("?") === -1 ? "?" : "&") + "popup=true"
+ const f = new URL(e, window.location.href)
+ const m = new URLSearchParams(window.location.search)
+ u.forEach((n) => {
+ const t = f.searchParams.getAll(n).find((n) => n.trim() !== "" && n.length <= 2048)
+ if (t !== undefined) return void f.searchParams.set(n, t)
+ const e = m.getAll(n).find((n) => n.trim() !== "" && n.length <= 2048)
+ e !== undefined && f.searchParams.set(n, e)
+ })
+ f.searchParams.set("popup", "true"), (e = f.toString())
const t = n?.emoji || "💬"
const i = n?.position === "left" ? "nf-left" : ""
const o = n?.bgcolor || "#3B82F6"
diff --git a/client/public/widgets/embed.js b/client/public/widgets/embed.js
index 9f648fd86..99c378e36 100644
--- a/client/public/widgets/embed.js
+++ b/client/public/widgets/embed.js
@@ -96,6 +96,11 @@
})();
(function () {
+ const attributionParameters = [
+ 'utm_source', 'utm_medium', 'utm_campaign', 'utm_id', 'utm_term', 'utm_content',
+ 'utm_source_platform', 'utm_creative_format', 'utm_marketing_tactic',
+ 'gclid', 'gbraid', 'wbraid', 'dclid', 'fbclid', 'ttclid', 'msclkid'
+ ]
const nfData = JSON.parse(document.currentScript.getAttribute("data-nf"))
let formUrl = nfData?.formurl || null
if (
@@ -107,8 +112,25 @@
return false
}
- // Add popup param to formUrl
- formUrl = formUrl + (formUrl.indexOf("?") === -1 ? "?" : "&") + "popup=true"
+ // Add parent-page attribution without overriding explicit iframe parameters.
+ const resolvedFormUrl = new URL(formUrl, window.location.href)
+ const parentParams = new URLSearchParams(window.location.search)
+ attributionParameters.forEach((parameter) => {
+ const iframeValue = resolvedFormUrl.searchParams.getAll(parameter).find(candidate => (
+ candidate.trim() !== '' && candidate.length <= 2048
+ ))
+ if (iframeValue !== undefined) {
+ resolvedFormUrl.searchParams.set(parameter, iframeValue)
+ return
+ }
+
+ const value = parentParams.getAll(parameter).find(candidate => (
+ candidate.trim() !== '' && candidate.length <= 2048
+ ))
+ if (value !== undefined) resolvedFormUrl.searchParams.set(parameter, value)
+ })
+ resolvedFormUrl.searchParams.set('popup', 'true')
+ formUrl = resolvedFormUrl.toString()
// Settings
const emoji = nfData?.emoji || "💬"
diff --git a/client/public/widgets/opnform-sdk.js b/client/public/widgets/opnform-sdk.js
index 955b8f024..ec2ddb200 100644
--- a/client/public/widgets/opnform-sdk.js
+++ b/client/public/widgets/opnform-sdk.js
@@ -21,6 +21,24 @@
// Message protocol prefix
const MSG_PREFIX = 'opnform:'
+ const ATTRIBUTION_PARAMETERS = [
+ 'utm_source', 'utm_medium', 'utm_campaign', 'utm_id', 'utm_term', 'utm_content',
+ 'utm_source_platform', 'utm_creative_format', 'utm_marketing_tactic',
+ 'gclid', 'gbraid', 'wbraid', 'dclid', 'fbclid', 'ttclid', 'msclkid'
+ ]
+ const ATTRIBUTION_MAX_VALUE_LENGTH = 2048
+
+ function getPageAttribution() {
+ const params = new URLSearchParams(window.location.search)
+ return ATTRIBUTION_PARAMETERS.reduce((attribution, parameter) => {
+ const value = params.getAll(parameter).find(candidate => (
+ candidate.trim() !== '' && candidate.length <= ATTRIBUTION_MAX_VALUE_LENGTH
+ ))
+ if (value !== undefined) attribution[parameter] = value
+ return attribution
+ }, {})
+ }
+
// Event types
const EVENTS = {
READY: 'ready',
@@ -161,6 +179,7 @@
formSlug: this.slug,
_sdkToken: this._sdkToken,
parentOrigin: window.location.origin,
+ trackingParameters: getPageAttribution(),
}, this._targetOrigin)
}
diff --git a/client/public/widgets/opnform-sdk.min.js b/client/public/widgets/opnform-sdk.min.js
index 955b8f024..ec2ddb200 100644
--- a/client/public/widgets/opnform-sdk.min.js
+++ b/client/public/widgets/opnform-sdk.min.js
@@ -21,6 +21,24 @@
// Message protocol prefix
const MSG_PREFIX = 'opnform:'
+ const ATTRIBUTION_PARAMETERS = [
+ 'utm_source', 'utm_medium', 'utm_campaign', 'utm_id', 'utm_term', 'utm_content',
+ 'utm_source_platform', 'utm_creative_format', 'utm_marketing_tactic',
+ 'gclid', 'gbraid', 'wbraid', 'dclid', 'fbclid', 'ttclid', 'msclkid'
+ ]
+ const ATTRIBUTION_MAX_VALUE_LENGTH = 2048
+
+ function getPageAttribution() {
+ const params = new URLSearchParams(window.location.search)
+ return ATTRIBUTION_PARAMETERS.reduce((attribution, parameter) => {
+ const value = params.getAll(parameter).find(candidate => (
+ candidate.trim() !== '' && candidate.length <= ATTRIBUTION_MAX_VALUE_LENGTH
+ ))
+ if (value !== undefined) attribution[parameter] = value
+ return attribution
+ }, {})
+ }
+
// Event types
const EVENTS = {
READY: 'ready',
@@ -161,6 +179,7 @@
formSlug: this.slug,
_sdkToken: this._sdkToken,
parentOrigin: window.location.origin,
+ trackingParameters: getPageAttribution(),
}, this._targetOrigin)
}
diff --git a/client/test/e2e/opnform-flows.spec.ts b/client/test/e2e/opnform-flows.spec.ts
index e8e567478..60c3db823 100644
--- a/client/test/e2e/opnform-flows.spec.ts
+++ b/client/test/e2e/opnform-flows.spec.ts
@@ -356,6 +356,18 @@ async function apiCreateForm(request: APIRequestContext, options: {
throw new Error(`Failed to create form via API (${lastFailure?.status}): ${lastFailure?.body}`)
}
+async function apiListSubmissions(request: APIRequestContext, token: string, slug: string) {
+ const response = await request.get(`${API_BASE_URL}/open/forms/${slug}/submissions`, {
+ headers: {
+ Accept: "application/json",
+ Authorization: `Bearer ${token}`,
+ },
+ })
+
+ expect(response.ok()).toBeTruthy()
+ return response.json()
+}
+
async function submitPublicForm(page: Page, slug: string, visitorName = "Playwright Visitor") {
const visitorEmail = uniqueEmail("visitor")
@@ -657,6 +669,145 @@ test("public submissions are accepted and visible in the submissions dashboard",
await expect(page.getByText(visitorEmail)).toBeVisible()
})
+test("public form URL attribution is stored separately from submitted answers", async ({ page, request }) => {
+ const form = await apiCreateForm(request, { title: uniqueTitle("Attributed Submission") })
+ const visitorName = `Attributed Visitor ${Date.now()}`
+ const visitorEmail = uniqueEmail("attributed")
+
+ await gotoPageWithRetry(
+ page,
+ `/forms/${form.slug}?utm_source=playwright&utm_campaign=e2e&gclid=browser-click&email=must-not-track`,
+ async () => {
+ await expect(page.getByTestId("public-form-page")).toBeVisible()
+ },
+ )
+ await fillFieldInput(page, "default_name", visitorName)
+ await fillFieldInput(page, "default_email", visitorEmail)
+ await fillFieldInput(page, "default_message", "Attribution browser test")
+ await page.getByRole("button", { name: /submit/i }).click()
+ await expectSubmissionSuccess(page)
+
+ const token = await apiLogin(request)
+ const submissionsResponse = await request.get(
+ `${API_BASE_URL}/open/forms/${form.slug}/submissions`,
+ {
+ headers: {
+ Accept: "application/json",
+ Authorization: `Bearer ${token}`,
+ },
+ },
+ )
+
+ expect(submissionsResponse.ok()).toBeTruthy()
+ const submissions = await submissionsResponse.json()
+ const submission = submissions.data.find((record: {
+ data: Record<string, unknown>,
+ }) => record.data.default_name === visitorName)
+
+ expect(submission).toBeTruthy()
+ expect(submission.data).not.toHaveProperty("tracking_parameters")
+ expect(submission.meta).toEqual({
+ attribution: {
+ utm_source: "playwright",
+ utm_campaign: "e2e",
+ gclid: "browser-click",
+ },
+ })
+
+ await loginUi(page)
+ await page.goto(`/forms/${form.slug}/show/submissions`)
+ await expect(page.getByTestId("form-submissions-page")).toBeVisible()
+ await page.getByRole("button", { name: "Columns", exact: true }).click()
+
+ const columnsDialog = page.getByRole("dialog", { name: "Columns" })
+ await expect(columnsDialog.getByText("utm_source", { exact: true })).toHaveCount(0)
+ await columnsDialog.getByRole("button", { name: /Attribution & tracking/ }).click()
+ await expect(columnsDialog.getByText("utm_source", { exact: true })).toBeVisible()
+ await columnsDialog.getByRole("button", { name: "Show detected", exact: true }).click()
+
+ const attributedRow = page.getByRole("row").filter({ hasText: visitorName })
+ await expect(attributedRow).toContainText("playwright")
+ await expect(attributedRow).toContainText("e2e")
+ await expect(attributedRow).toContainText("browser-click")
+
+ await columnsDialog.getByRole("button", { name: "Hide URL parameters", exact: true }).click()
+ await expect(page.getByRole("columnheader", { name: "utm_source", exact: true })).toHaveCount(0)
+ await expect(page.getByRole("columnheader", { name: "utm_campaign", exact: true })).toHaveCount(0)
+ await expect(page.getByRole("columnheader", { name: "gclid", exact: true })).toHaveCount(0)
+})
+
+test("SDK parent attribution is captured before an embedded auto-submit", async ({ page, request }) => {
+ const form = await apiCreateForm(request, {
+ title: uniqueTitle("SDK Auto Submit Attribution"),
+ payloadOverrides: {
+ properties: [
+ {
+ type: "nf-text",
+ content: "<h1>SDK auto-submit attribution</h1>",
+ name: "Title",
+ id: "default_title",
+ },
+ buildTextField("sdk_auto_name", "Name"),
+ ],
+ },
+ })
+ const token = await apiLogin(request)
+ const iframeUrl = `/forms/${form.slug}?auto_submit=true&sdk_auto_name=Auto%20SDK`
+
+ await page.goto("/?utm_source=sdk-parent&utm_campaign=auto-submit")
+ await page.setContent(`
+ <!doctype html>
+ <html>
+ <body>
+ <iframe id="${form.slug}" src="${iframeUrl}"></iframe>
+ <script>
+ setTimeout(() => {
+ const sdk = document.createElement('script')
+ sdk.src = '/widgets/opnform-sdk.js'
+ sdk.onload = () => window.opnform.init({ autoResize: false, preventRedirect: true })
+ document.body.appendChild(sdk)
+ }, 750)
+ </script>
+ </body>
+ </html>
+ `)
+
+ let submission: { meta?: { attribution?: Record<string, string> } } | undefined
+ await expect.poll(async () => {
+ const submissions = await apiListSubmissions(request, token, form.slug)
+ submission = submissions.data.find((record: { data: Record<string, unknown> }) => (
+ record.data.sdk_auto_name === "Auto SDK"
+ ))
+ return submission
+ }, { timeout: 20_000 }).toBeTruthy()
+
+ expect(submission?.meta?.attribution).toEqual({
+ utm_source: "sdk-parent",
+ utm_campaign: "auto-submit",
+ })
+})
+
+test("popup embed falls back to valid parent attribution when its form URL value is empty", async ({ page, request }) => {
+ const form = await apiCreateForm(request, { title: uniqueTitle("Popup Attribution") })
+ const formUrl = `/forms/${form.slug}?utm_source=`
+ const widgetData = JSON.stringify({ formurl: formUrl }).replaceAll('"', '&quot;')
+
+ await page.goto("/?utm_source=popup-parent&utm_campaign=popup-test")
+ await page.setContent(`
+ <!doctype html>
+ <html>
+ <body>
+ <script data-nf="${widgetData}" src="/widgets/embed.js"></script>
+ </body>
+ </html>
+ `)
+ await page.locator(".nf-emoji").click()
+
+ const popupUrl = new URL(await page.locator(".nf-popup iframe").getAttribute("src") || "", page.url())
+ expect(popupUrl.searchParams.get("utm_source")).toBe("popup-parent")
+ expect(popupUrl.searchParams.get("utm_campaign")).toBe("popup-test")
+})
+
test("classic public form submits successfully with mixed field components", async ({ page, request }) => {
const form = await apiCreateForm(request, {
title: uniqueTitle("Mixed Components"),
diff --git a/client/test/unit/embed-attribution.test.ts b/client/test/unit/embed-attribution.test.ts
new file mode 100644
index 000000000..6923b4a0d
--- /dev/null
+++ b/client/test/unit/embed-attribution.test.ts
@@ -0,0 +1,61 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { JSDOM } from 'jsdom'
+
+const embedSources = [
+ ['source', readFileSync(resolve(__dirname, '../../public/widgets/embed.js'), 'utf8')],
+ ['minified', readFileSync(resolve(__dirname, '../../public/widgets/embed-min.js'), 'utf8')],
+] as const
+
+describe.each(embedSources)('popup embed attribution (%s)', (_variant, embedSource) => {
+ it('fills missing iframe attribution from the parent without forwarding arbitrary parameters', () => {
+ const dom = new JSDOM('<!doctype html><html><head></head><body></body></html>', {
+ url: 'https://embedder.example.test/?utm_source=parent&utm_campaign=launch&[email protected]',
+ runScripts: 'outside-only',
+ })
+ const script = dom.window.document.createElement('script')
+ script.setAttribute('data-nf', JSON.stringify({
+ formurl: 'https://forms.example.test/forms/demo?utm_source=iframe',
+ }))
+ Object.defineProperty(dom.window.document, 'currentScript', {
+ configurable: true,
+ value: script,
+ })
+
+ dom.window.eval(embedSource)
+ const button = dom.window.document.querySelector('.nf-emoji') as HTMLElement
+ button.click()
+
+ const iframe = dom.window.document.querySelector('iframe') as HTMLIFrameElement
+ const iframeUrl = new URL(iframe.src)
+ expect(iframeUrl.searchParams.get('utm_source')).toBe('iframe')
+ expect(iframeUrl.searchParams.get('utm_campaign')).toBe('launch')
+ expect(iframeUrl.searchParams.get('email')).toBeNull()
+ expect(iframeUrl.searchParams.get('popup')).toBe('true')
+ })
+
+ it('falls back to valid parent attribution when the iframe value is invalid', () => {
+ const dom = new JSDOM('<!doctype html><html><head></head><body></body></html>', {
+ url: 'https://embedder.example.test/?utm_source=parent&utm_campaign=launch',
+ runScripts: 'outside-only',
+ })
+ const script = dom.window.document.createElement('script')
+ script.setAttribute('data-nf', JSON.stringify({
+ formurl: `https://forms.example.test/forms/demo?utm_source=&utm_campaign=${'x'.repeat(2049)}`,
+ }))
+ Object.defineProperty(dom.window.document, 'currentScript', {
+ configurable: true,
+ value: script,
+ })
+
+ dom.window.eval(embedSource)
+ const button = dom.window.document.querySelector('.nf-emoji') as HTMLElement
+ button.click()
+
+ const iframe = dom.window.document.querySelector('iframe') as HTMLIFrameElement
+ const iframeUrl = new URL(iframe.src)
+ expect(iframeUrl.searchParams.get('utm_source')).toBe('parent')
+ expect(iframeUrl.searchParams.get('utm_campaign')).toBe('launch')
+ })
+})
diff --git a/client/test/unit/opnform-sdk-postmessage.test.ts b/client/test/unit/opnform-sdk-postmessage.test.ts
index 376d51947..313564284 100644
--- a/client/test/unit/opnform-sdk-postmessage.test.ts
+++ b/client/test/unit/opnform-sdk-postmessage.test.ts
@@ -4,6 +4,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
import { JSDOM } from 'jsdom'
const sdkSource = readFileSync(resolve(__dirname, '../../public/widgets/opnform-sdk.js'), 'utf8')
+const sdkMinSource = readFileSync(resolve(__dirname, '../../public/widgets/opnform-sdk.min.js'), 'utf8')
function getIframeOrigin(window: Window, iframe: HTMLIFrameElement) {
return new URL(iframe.src, window.location.href).origin
@@ -152,6 +153,36 @@ describe('OpnForm public SDK postMessage security', () => {
)
})
+ it.each([
+ ['source', sdkSource],
+ ['minified', sdkMinSource],
+ ])('sends allowlisted parent attribution without leaking arbitrary query parameters (%s)', (_variant, source) => {
+ const dom = new JSDOM(
+ '<!doctype html><html><body><iframe id="demo" src="https://forms.example.test/forms/demo"></iframe></body></html>',
+ {
+ url: 'https://embedder.example.test/?utm_source=facebook&gclid=click-id&[email protected]',
+ runScripts: 'outside-only',
+ },
+ )
+
+ dom.window.eval(source)
+ const iframe = dom.window.document.getElementById('demo') as HTMLIFrameElement
+ vi.spyOn(iframe.contentWindow!, 'postMessage').mockImplementation(() => {})
+ dom.window.opnform._forms = {}
+ dom.window.opnform.init({ autoResize: false })
+
+ expect(iframe.contentWindow!.postMessage).toHaveBeenCalledWith(
+ expect.objectContaining({
+ type: 'opnform:handshake',
+ trackingParameters: {
+ utm_source: 'facebook',
+ gclid: 'click-id',
+ },
+ }),
+ 'https://forms.example.test',
+ )
+ })
+
it('does not create an unhandled rejection when passive handshake times out', async () => {
vi.useFakeTimers()
diff --git a/client/test/unit/submission-attribution.test.ts b/client/test/unit/submission-attribution.test.ts
new file mode 100644
index 000000000..00c43cbbf
--- /dev/null
+++ b/client/test/unit/submission-attribution.test.ts
@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest'
+import {
+ ATTRIBUTION_MAX_VALUE_LENGTH,
+ ATTRIBUTION_PARAMETER_LABELS,
+ ATTRIBUTION_PARAMETERS,
+ attributionColumnAccessor,
+ attributionColumnId,
+ attributionParameterFromColumnId,
+ detectedAttributionParameters,
+ extractAttribution,
+ isColumnVisibilityTransition,
+ mergeAttribution,
+ sanitizeAttribution,
+} from '../../lib/forms/submissionAttribution.js'
+
+describe('submission attribution', () => {
+ it('captures the complete supported parameter contract', () => {
+ expect(ATTRIBUTION_PARAMETERS).toEqual([
+ 'utm_source', 'utm_medium', 'utm_campaign', 'utm_id', 'utm_term', 'utm_content',
+ 'utm_source_platform', 'utm_creative_format', 'utm_marketing_tactic',
+ 'gclid', 'gbraid', 'wbraid', 'dclid', 'fbclid', 'ttclid', 'msclkid',
+ ])
+ })
+
+ it('extracts supported values and ignores arbitrary query parameters', () => {
+ const attribution = extractAttribution('[email protected]&utm_source=google&gclid=click-id')
+
+ expect(attribution).toEqual({ utm_source: 'google', gclid: 'click-id' })
+ })
+
+ it('uses the first non-empty occurrence', () => {
+ expect(extractAttribution('?utm_campaign=&utm_campaign=first&utm_campaign=second'))
+ .toEqual({ utm_campaign: 'first' })
+ })
+
+ it('drops empty, non-string, and oversized values', () => {
+ expect(sanitizeAttribution({
+ utm_source: ' ',
+ utm_medium: ['cpc'],
+ gclid: 'x'.repeat(ATTRIBUTION_MAX_VALUE_LENGTH + 1),
+ fbclid: 'valid',
+ secret: 'ignored',
+ })).toEqual({ fbclid: 'valid' })
+ })
+
+ it('gives explicit iframe parameters precedence over parent parameters', () => {
+ const iframeAttribution = { utm_source: 'partner', utm_medium: 'embed' }
+ const parentAttribution = { utm_source: 'facebook', utm_campaign: 'summer' }
+
+ expect(mergeAttribution(iframeAttribution, parentAttribution)).toEqual({
+ utm_source: 'partner',
+ utm_medium: 'embed',
+ utm_campaign: 'summer',
+ })
+ expect(iframeAttribution).toEqual({ utm_source: 'partner', utm_medium: 'embed' })
+ expect(parentAttribution).toEqual({ utm_source: 'facebook', utm_campaign: 'summer' })
+ })
+
+ it('uses namespaced table column identifiers', () => {
+ expect(attributionColumnId('utm_source')).toBe('meta.attribution.utm_source')
+ })
+
+ it('reads namespaced attribution columns from flat table rows', () => {
+ const row = { 'meta.attribution.utm_source': 'newsletter' }
+
+ expect(attributionColumnAccessor('utm_source')(row)).toBe('newsletter')
+ })
+
+ it('identifies attribution columns and provides readable labels', () => {
+ expect(attributionParameterFromColumnId('meta.attribution.utm_campaign')).toBe('utm_campaign')
+ expect(attributionParameterFromColumnId('utm_campaign')).toBeNull()
+ expect(attributionParameterFromColumnId('default_email')).toBeNull()
+ expect(ATTRIBUTION_PARAMETER_LABELS.utm_campaign).toBe('Campaign')
+ })
+
+ it('detects only parameters containing submission values', () => {
+ expect(detectedAttributionParameters([
+ {
+ 'meta.attribution.utm_source': 'newsletter',
+ 'meta.attribution.utm_medium': '',
+ },
+ {
+ 'meta.attribution.gclid': 'google-click',
+ },
+ ])).toEqual(['utm_source', 'gclid'])
+ })
+
+ it('changes visibility only when dragging between visible and hidden sections', () => {
+ expect(isColumnVisibilityTransition('hidden', 'visible')).toBe(true)
+ expect(isColumnVisibilityTransition('visible', 'hidden')).toBe(true)
+ expect(isColumnVisibilityTransition('hidden', 'hidden')).toBe(false)
+ expect(isColumnVisibilityTransition(undefined, 'hidden')).toBe(false)
+ })
+})
diff --git a/client/test/unit/use-sdk-bridge-postmessage.test.ts b/client/test/unit/use-sdk-bridge-postmessage.test.ts
index 8b0131db2..194bd060b 100644
--- a/client/test/unit/use-sdk-bridge-postmessage.test.ts
+++ b/client/test/unit/use-sdk-bridge-postmessage.test.ts
@@ -29,6 +29,7 @@ function createBridgeHarness(dom: JSDOM, options: {
initialSdkToken?: string | null
initialTrustedOrigin?: string | null
onCommand?: ReturnType<typeof vi.fn>
+ onHandshake?: ReturnType<typeof vi.fn>
} = {}) {
const { window, mockParent } = installIframeWindow(dom)
const parentMessages: Array<{ message: unknown, origin: string }> = []
@@ -47,6 +48,7 @@ function createBridgeHarness(dom: JSDOM, options: {
mockParent.postMessage(message, origin)
},
onCommand,
+ onHandshake: options.onHandshake,
})
function dispatchMessage(data: Record<string, unknown>, overrides: {
@@ -100,6 +102,36 @@ describe('SDK bridge messaging security', () => {
})
})
+ it('delivers parent attribution only after a trusted handshake', () => {
+ const onHandshake = vi.fn()
+ const { dispatchMessage } = createBridgeHarness(dom, { onHandshake })
+
+ dispatchMessage({
+ type: `${MSG_PREFIX}handshake`,
+ formSlug: FORM_SLUG,
+ _sdkToken: 'bridge-token',
+ parentOrigin: PARENT_ORIGIN,
+ trackingParameters: { utm_source: 'parent', secret: 'ignored-by-form-manager' },
+ })
+
+ expect(onHandshake).toHaveBeenCalledWith({ utm_source: 'parent' })
+ })
+
+ it('does not deliver attribution from an untrusted handshake', () => {
+ const onHandshake = vi.fn()
+ const { dispatchMessage } = createBridgeHarness(dom, { onHandshake })
+
+ dispatchMessage({
+ type: `${MSG_PREFIX}handshake`,
+ formSlug: FORM_SLUG,
+ _sdkToken: 'bridge-token',
+ parentOrigin: 'https://attacker.example.test',
+ trackingParameters: { utm_source: 'attacker' },
+ })
+
+ expect(onHandshake).not.toHaveBeenCalled()
+ })
+
it('rejects handshake when parentOrigin does not match event origin', () => {
const { bridge, parentMessages, dispatchMessage } = createBridgeHarness(dom)
diff --git a/docs/api-reference/integrations/webhook-security.mdx b/docs/api-reference/integrations/webhook-security.mdx
index 1774a1907..090e789d9 100644
--- a/docs/api-reference/integrations/webhook-security.mdx
+++ b/docs/api-reference/integrations/webhook-security.mdx
@@ -201,6 +201,12 @@ X-Custom-Header: custom-value
"name": "Name",
"type": "text"
}
+ },
+ "meta": {
+ "attribution": {
+ "utm_source": "newsletter",
+ "utm_campaign": "summer-launch"
+ }
}
}
```
@@ -211,6 +217,10 @@ the same `form_id`, `form_title`, `form_slug`, `submission_id`, optional
`edit_link`, and `data` properties while omitting the deprecated `submission`
and `message` properties.
+When campaign parameters were captured, machine-oriented webhook integrations
+also receive them under `meta.attribution`. The `meta` property is omitted when
+the submission has no attribution.
+
## Security Best Practices
<Tip>
diff --git a/docs/api-reference/openapi.yaml b/docs/api-reference/openapi.yaml
index cdd6750b9..d5898a7a7 100644
--- a/docs/api-reference/openapi.yaml
+++ b/docs/api-reference/openapi.yaml
@@ -579,6 +579,8 @@ paths:
is_partial:
type: boolean
description: "If you want to submit your form as partial"
+ tracking_parameters:
+ $ref: "#/components/schemas/SubmissionAttribution"
responses:
"200":
description: "Form submission saved successfully"
@@ -733,7 +735,7 @@ paths:
type: object
additionalProperties:
type: boolean
- description: "Object mapping field IDs to booleans to include columns in CSV."
+ description: "Object mapping field IDs, system columns, or namespaced attribution columns (for example meta.attribution.utm_source) to booleans."
responses:
"200":
description: "Synchronous export (CSV file) or asynchronous export (job status)"
@@ -1506,6 +1508,33 @@ components:
description: "Contains form field responses plus metadata (status, created_at, id)"
additionalProperties: true
readOnly: true
+ meta:
+ type: object
+ readOnly: true
+ properties:
+ attribution:
+ $ref: "#/components/schemas/SubmissionAttribution"
+ SubmissionAttribution:
+ type: object
+ description: "Allowlisted campaign attribution. Values are strings with a maximum length of 2,048 characters."
+ additionalProperties: false
+ properties:
+ utm_source: { type: string, maxLength: 2048 }
+ utm_medium: { type: string, maxLength: 2048 }
+ utm_campaign: { type: string, maxLength: 2048 }
+ utm_id: { type: string, maxLength: 2048 }
+ utm_term: { type: string, maxLength: 2048 }
+ utm_content: { type: string, maxLength: 2048 }
+ utm_source_platform: { type: string, maxLength: 2048 }
+ utm_creative_format: { type: string, maxLength: 2048 }
+ utm_marketing_tactic: { type: string, maxLength: 2048 }
+ gclid: { type: string, maxLength: 2048 }
+ gbraid: { type: string, maxLength: 2048 }
+ wbraid: { type: string, maxLength: 2048 }
+ dclid: { type: string, maxLength: 2048 }
+ fbclid: { type: string, maxLength: 2048 }
+ ttclid: { type: string, maxLength: 2048 }
+ msclkid: { type: string, maxLength: 2048 }
UserWorkspaceMember:
type: object
properties:
diff --git a/docs/api-reference/submissions/create-submission.mdx b/docs/api-reference/submissions/create-submission.mdx
index 3cde8741b..94d33f31f 100644
--- a/docs/api-reference/submissions/create-submission.mdx
+++ b/docs/api-reference/submissions/create-submission.mdx
@@ -34,6 +34,10 @@ Content-Type: application/json
{
"completion_time": 10,
+"tracking_parameters": {
+ "utm_source": "newsletter",
+ "utm_campaign": "summer-launch"
+},
"3700d380-197b-47b9-a008-3acc31bbd506": "Alice",
"12461db5-0c19-429e-840b-8de1e359c42f": "[email protected]"
}
@@ -50,6 +54,16 @@ Content-Type: application/json
under form settings.
</ParamField>
+<ParamField body="tracking_parameters" type="object">
+ Optional campaign attribution. Supported keys are `utm_source`,
+ `utm_medium`, `utm_campaign`, `utm_id`, `utm_term`, `utm_content`,
+ `utm_source_platform`, `utm_creative_format`, `utm_marketing_tactic`,
+ `gclid`, `gbraid`, `wbraid`, `dclid`, `fbclid`, `ttclid`, and `msclkid`.
+ Values must be non-empty strings of at most 2,048 characters. Unsupported
+ keys are rejected. Attribution is stored separately from form answers and
+ cannot be changed after the submission is created.
+</ParamField>
+
### Request Body
<ParamField body="[field_id]" type="string|number|boolean|array">
diff --git a/docs/api-reference/submissions/export-submissions-csv.mdx b/docs/api-reference/submissions/export-submissions-csv.mdx
index cb607b89b..8c8ede00a 100644
--- a/docs/api-reference/submissions/export-submissions-csv.mdx
+++ b/docs/api-reference/submissions/export-submissions-csv.mdx
@@ -29,7 +29,7 @@ Authorization: Bearer <token>
| Field | Type | Required | Description |
| ------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------- |
-| columns | object | Yes | Keys are field IDs (or `created_at`); values are booleans indicating whether to include the column in the export. |
+| columns | object | Yes | Keys are field IDs, system columns, or attribution columns such as `meta.attribution.utm_source`; values indicate whether to include them. |
Example payload exporting two fields and the created_at timestamp:
@@ -38,6 +38,7 @@ Example payload exporting two fields and the created_at timestamp:
"columns": {
"field_name": true,
"field_email": true,
+ "meta.attribution.utm_source": true,
"created_at": true
}
}
diff --git a/docs/api-reference/submissions/list-submissions.mdx b/docs/api-reference/submissions/list-submissions.mdx
index b3167d478..2c0c96018 100644
--- a/docs/api-reference/submissions/list-submissions.mdx
+++ b/docs/api-reference/submissions/list-submissions.mdx
@@ -56,7 +56,13 @@ Authorization: Bearer <token>
},
"completion_time": 45,
"form_id": 123,
- "id": 615432
+ "id": 615432,
+ "meta": {
+ "attribution": {
+ "utm_source": "newsletter",
+ "utm_campaign": "summer-launch"
+ }
+ }
}
],
"links": {
@@ -104,6 +110,7 @@ Each submission object contains:
| `completion_time` | number/null | Time taken to complete the form in seconds |
| `form_id` | number | ID of the parent form |
| `id` | number | Unique submission ID |
+| `meta` | object/null | Owner-only submission metadata, including campaign attribution when captured |
#### Data Object Structure
diff --git a/docs/embedding/javascript-sdk.mdx b/docs/embedding/javascript-sdk.mdx
index 46c3bb429..323024aa2 100644
--- a/docs/embedding/javascript-sdk.mdx
+++ b/docs/embedding/javascript-sdk.mdx
@@ -23,6 +23,22 @@ Include the SDK script after your form iframe:
them. No additional setup required.
</Note>
+## Automatic campaign attribution
+
+The SDK automatically captures supported campaign parameters from the parent
+page and stores them with the submission under `meta.attribution`. Parameters
+already present in the iframe `src` take precedence over values from the parent
+page.
+
+Supported campaign parameters are `utm_source`, `utm_medium`, `utm_campaign`,
+`utm_id`, `utm_term`, `utm_content`, `utm_source_platform`,
+`utm_creative_format`, `utm_marketing_tactic`, `gclid`, `gbraid`, `wbraid`,
+`dclid`, `fbclid`, `ttclid`, and `msclkid`.
+
+Only these parameters are transmitted to the form. Other URL parameters and the
+complete parent URL are not captured. A raw cross-origin iframe without the SDK
+can only capture parameters included directly in its own `src`.
+
## Quick Start
```javascript
@@ -50,7 +66,7 @@ Listen to form events to trigger custom actions, send data to analytics, or inte
| Event | Description | Payload |
| -------------- | ---------------------------------- | ------------------------------------------------------- |
| `ready` | Form iframe loaded and ready | `{ form, slug, id }` |
-| `submit` | Form submitted successfully | `{ form, data, submissionId, completionTime }` |
+| `submit` | Form submitted successfully | `{ form, data, submissionId, completionTime, meta? }` |
| `submitStart` | Submission started | `{ form }` |
| `submitError` | Submission failed | `{ form, errors }` |
| `dataChange` | Form data changed | `{ form, data, changedField, previousValue, newValue }` |
@@ -68,6 +84,7 @@ Listen to form events to trigger custom actions, send data to analytics, or inte
```javascript Single Event
opnform.on('submit', function(data) {
console.log('Form submitted:', data);
+ console.log('Campaign attribution:', data.meta?.attribution);
});
```
diff --git a/docs/front-end/javascript-sdk.mdx b/docs/front-end/javascript-sdk.mdx
index f755964e6..9d723361d 100644
--- a/docs/front-end/javascript-sdk.mdx
+++ b/docs/front-end/javascript-sdk.mdx
@@ -23,6 +23,22 @@ Include the SDK script after your form iframe:
them. No additional setup required.
</Note>
+## Automatic campaign attribution
+
+The SDK automatically captures supported campaign parameters from the parent
+page and stores them with the submission under `meta.attribution`. Parameters
+already present in the iframe `src` take precedence over values from the parent
+page.
+
+Supported campaign parameters are `utm_source`, `utm_medium`, `utm_campaign`,
+`utm_id`, `utm_term`, `utm_content`, `utm_source_platform`,
+`utm_creative_format`, `utm_marketing_tactic`, `gclid`, `gbraid`, `wbraid`,
+`dclid`, `fbclid`, `ttclid`, and `msclkid`.
+
+Only these parameters are transmitted to the form. Other URL parameters and the
+complete parent URL are not captured. A raw cross-origin iframe without the SDK
+can only capture parameters included directly in its own `src`.
+
## Quick Start
```javascript
@@ -50,7 +66,7 @@ Listen to form events to trigger custom actions, send data to analytics, or inte
| Event | Description | Payload |
| -------------- | ---------------------------------- | ------------------------------------------------------- |
| `ready` | Form iframe loaded and ready | `{ form, slug, id }` |
-| `submit` | Form submitted successfully | `{ form, data, submissionId, completionTime }` |
+| `submit` | Form submitted successfully | `{ form, data, submissionId, completionTime, meta? }` |
| `submitStart` | Submission started | `{ form }` |
| `submitError` | Submission failed | `{ form, errors }` |
| `dataChange` | Form data changed | `{ form, data, changedField, previousValue, newValue }` |