Umbraco Package

The Lantern Umbraco package provides a clean way to install the Lantern widget on an Umbraco site. It installs via NuGet and adds a Lantern section to the Umbraco backoffice where you can enter the embed key.

#What the package does

• Adds the Lantern widget script tag to the frontend layout of your Umbraco site
• Provides a Lantern configuration section in the Umbraco backoffice
• Only shows the widget to logged-in Umbraco backoffice users (auth gate is built in)

#Requirements

• Umbraco 10 or later (including Umbraco v17 LTS)
• .NET 6 or later
• A Lantern account with at least one client configured

#Installation

#Via NuGet Package Manager (Visual Studio)

Install-Package Lantern.Umbraco

#Via .NET CLI

dotnet add package Lantern.Umbraco

#Via NuGet Package Manager UI

1. In Visual Studio, right-click your project and select Manage NuGet Packages.
2. Search for Lantern.Umbraco.
3. Install the latest version.

#Configuration

After installing the package, add your embed key to your Umbraco configuration.

#Option 1: Backoffice (recommended)

1. Log into the Umbraco backoffice.
2. Go to the Lantern section in the top navigation.
3. Enter your Embed Key — find this in your Lantern workspace under Clients → [your client] → Embed.
4. Save.

#Option 2: appsettings.json

You can also set the embed key via configuration:

{
  "Lantern": {
    "EmbedKey": "YOUR_EMBED_KEY_HERE"
  }
}

This is useful in CI/CD environments where you want to manage the key via environment variables:

{
  "Lantern": {
    "EmbedKey": ""
  }
}

LANTERN__EMBEDKEY=your-embed-key-here

#Registration

In your Startup.cs or Program.cs, add:

builder.Services.AddLantern();

And in the app pipeline:

app.UseLantern();

The package handles script injection automatically once registered.

#Testing

1. Log into the Umbraco backoffice.
2. Open a new tab and visit the frontend of the Umbraco site.
3. You should see the Lantern widget button on the page.
4. Submit a test issue and confirm it appears in your Lantern workspace under the correct client.

#Multi-site setups

If your Umbraco installation serves multiple sites (via Umbraco's multi-site feature), you can configure different embed keys per domain using the appsettings.json approach combined with environment-specific configuration files:

// appsettings.Production.json
{
  "Lantern": {
    "EmbedKey": "production-embed-key"
  }
}

Or pass it via environment variables in your deployment pipeline.

#Uninstalling

1. Remove the NuGet package: dotnet remove package Lantern.Umbraco
2. Remove the AddLantern() and UseLantern() calls from your startup code.
3. Remove the Lantern section from appsettings.json if present.

#Updating the embed key

If you regenerate the embed key in Lantern, update it in the Umbraco backoffice under Lantern → Settings (or update the appsettings.json / environment variable and redeploy).

#Troubleshooting

Widget not appearing:

• Confirm you are logged into the Umbraco backoffice in the same browser session
• Check the page source for the <script src="https://lanternhq.app/widget.js" ...> tag
• Open the browser console and look for errors from widget.js
• Confirm the umbracoPath cookie is set (check under Application → Cookies in browser DevTools)

Package not appearing in backoffice:

• Rebuild the project and restart the application
• Confirm AddLantern() and UseLantern() are called in the correct order in your startup code

Content Security Policy errors:

• Add lanternhq.app as an allowed script source in your CSP headers