Getting Started

Installation

CampaignCanvas is distributed as a NuGet package and targets Umbraco 17+ (Bellissima). Install it with the .NET CLI:

dotnet add package CampaignCanvas

Or add the package reference directly to your .csproj file:

<PackageReference Include="CampaignCanvas" Version="*" />

Run your Umbraco site after installing. CampaignCanvas automatically registers itself via IComposer, creates the required database tables through its migration plan, and adds the CampaignCanvas section to the backoffice. No manual configuration is required for basic usage.

Note

CampaignCanvas supports both SQLite and SQL Server. The migration plan detects your database provider automatically and runs the appropriate schema scripts.

Activate Your License

Localhost runs for free, so you can build and test without a license. Before you deploy to a staging or production domain, activate your license through the backoffice:

1. Copy your license key from the License Portal. Keys look like FF-XXXX-XXXX-XXXX-XXXX-XXXX.
2. In the Umbraco backoffice, open the CampaignCanvas section and go to License.
3. Paste the key into Change license key and save. The status flips to Active once the key is verified against the current domain.

One key, one Umbraco major

A license covers the Umbraco major version you bought it for (e.g. Umbraco 17) and activates up to three apex domains by default (www. is covered automatically per slot). Add more domain packs from the portal any time. Upgrading to a newer Umbraco major requires a new license.

Configuration

CampaignCanvas works out of the box with zero configuration. For production deployments you can fine-tune behavior through appsettings.json keys under the CampaignCanvas section.

Available Settings

Key	Description
TurnstileSiteKey	Cloudflare Turnstile site key for CAPTCHA protection
TurnstileSecretKey	Cloudflare Turnstile secret key
RecaptchaSiteKey	Google reCAPTCHA v3 site key
RecaptchaSecretKey	Google reCAPTCHA v3 secret key

The license key is not stored in appsettings.json— enter it through the backoffice License screen as described above.

Example Configuration

{
  "CampaignCanvas": {
    "TurnstileSiteKey": "0x4AAAAAAA...",
    "TurnstileSecretKey": "0x4AAAAAAA..."
  }
}

Rate Limiting

CampaignCanvas respects a named rate-limiting policy called "FormSubmission". Your host application is responsible for registering this policy using .NET Core’s built-in rate limiter. If no policy is registered, form submissions are not rate-limited.

// Program.cs
using System.Threading.RateLimiting;

builder.Services.AddRateLimiter(options =>
{
    options.AddFixedWindowLimiter("FormSubmission", opt =>
    {
        opt.PermitLimit = 5;
        opt.Window = TimeSpan.FromMinutes(1);
        opt.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
        opt.QueueLimit = 0;
    });
});

// ...

app.UseRateLimiter();

Important

Call app.UseRateLimiter() before app.UseEndpoints() (or app.MapControllers()) so the middleware runs ahead of CampaignCanvas’s submission endpoint.

Your First Form

With CampaignCanvas installed, you can create and publish a working form in a few clicks.

1. Grant Permissions

Before any user can see the CampaignCanvas section in the backoffice, their user group needs the CampaignCanvas section permission.

1. Go to Settings → User Groups in the Umbraco backoffice.
2. Open the user group you want to grant access to (e.g. Administrators).
3. Under Sections, enable CampaignCanvas.
4. Save the user group.

Users in that group will now see the CampaignCanvas section in the backoffice sidebar after logging out and back in.

Sensitive Data Permission

Umbraco ships with a built-in Sensitive data user group that controls access to confidential field values. Users who belong to this group can:

• View the actual values of fields marked as Sensitive (otherwise they see ******)
• Perform SAR (Subject Access Request) searches across all submissions
• Execute Right to Erasure operations to delete matching submissions

To assign it, go to Users, select a user, and under Assign access → Groups add the Sensitive data group. Only grant this to users who need to handle personal data requests.

2. Create the Form

1. Open the Umbraco backoffice and navigate to the CampaignCanvas section.
2. Click Create Form.
3. Give your form a name and alias (e.g. contact-form).

3. Add Fields

Drag fields from the palette onto the canvas. For a simple contact form, add:

• Text field — label it Name
• Email field — label it Email
• Textarea field — label it Message

4. Configure Settings

Open the Settings tab to customize the submit button label and the success message shown after a visitor submits the form.

5. Save & Publish

Click Save. Your form is now ready to be rendered on any page.

6. Render the Form

There are two ways to add a form to a page:

Option A: FormPicker Property Editor

Add a FormPickerproperty to your document type. Content editors can then select a form from the picker when editing a page. CampaignCanvas’s view component renders the selected form automatically.

Option B: ViewComponent (Direct)

Invoke the CampaignCanvasRenderer view component directly in a Razor template:

@await Component.InvokeAsync("CampaignCanvasRenderer", new { formAlias = "contact-form" })

7. Test the Form

Navigate to the page containing your form and submit a test entry. Then return to the backoffice and open the Submissionsinbox under the CampaignCanvas section — your entry should appear with all the field data.

Tip

Localhost submissions are always allowed, even without a license key. Activate your license (see Activate Your License) before deploying to a staging or production domain.

Requirements

Dependency	Minimum Version
.NET	10+
Umbraco	17.3.2+ (Bellissima)
Database	SQLite or SQL Server

CampaignCanvas has no additional runtime dependencies. All required JavaScript and CSS assets are bundled with the NuGet package and served from the backoffice automatically.