Kiwicodes.Beacon.HelpCenter.Blazor 1.2.5

Beacon Help Center (Blazor)

A drop-in, themeable customer help center component for Blazor — the same Client Help Center used in Beacon, packaged as a Razor Class Library you can embed in your own app. It renders the knowledge base, the request form and the ticket tracker from a single component. Point it at your Beacon API and your app's portal key, set a brand colour, and you're done.

It's built on Kiwicodes.Beacon.Sdk's BeaconPublicClient, so all calls go through the same public (/public/*) endpoints — no admin credentials, no HMAC signing required on the client.

The knowledge base opens on a category list (each with a book icon and an article count). It's a two-level accordion: clicking a category expands it to show any articles that sit directly under it, plus its folders (folder icon); clicking a folder expands its articles (document icon). Folders are a single level deep and optional — articles with no folder appear right under their category, and articles with no known category are grouped under General. Typing in the search box lists matching articles across everything.

Install

dotnet add package Kiwicodes.Beacon.HelpCenter

This pulls in Kiwicodes.Beacon.Sdk automatically.

.NET MAUI Blazor Hybrid

In a MAUI Blazor Hybrid solution, add the package reference to the MAUI host project, not only to the shared Razor class library where you use the component. The BlazorWebView loads assemblies from the host app's package, so a reference that lives solely in the shared RCL compiles fine but the DLL never ships — you'll hit Could not load file or assembly 'Beacon.HelpCenter' at render time. The same applies to its dependency Kiwicodes.Beacon.Sdk, which rides along automatically once the host references this package.

Quick start (no DI)

The component is fully self-contained — it manages its own navigation between the article list, an article, the request form and the ticket tracker. Drop it on any page:

@using Beacon.HelpCenter

<BeaconHelpCenter BaseUrl="https://your-beacon/api/"
                  PortalKey="pk_live_xxxxxxxx"
                  PrimaryColor="#e8590c" />

• BaseUrl — your Beacon API base, including the route prefix (e.g. .../api/).
• PortalKey — your app's portal key (the public key from Beacon's Settings → API Keys). This is what scopes the help center to your app's articles and tickets.
• PrimaryColor — your brand colour. The header gradient, buttons, links and accent tints are all derived from it.

With dependency injection (optional)

If you'd rather not repeat BaseUrl on every instance, register a client once:

// Program.cs
builder.Services.AddBeaconHelpCenter("https://your-beacon/api/");

<BeaconHelpCenter PortalKey="pk_live_xxxxxxxx" PrimaryColor="#e8590c" />

The component resolves its data source in this order: an explicit Client parameter → a BeaconPublicClient registered in DI → a client built from BaseUrl.

Verified users

If your app already knows who the user is, pass their name and email. The request form then pre-fills both fields, makes them read-only, and shows a Verified user badge — so signed-in users don't retype (or mistype) their details:

<BeaconHelpCenter BaseUrl="https://your-beacon/api/"
                  PortalKey="pk_live_xxxxxxxx"
                  VerifiedUserName="@user.DisplayName"
                  VerifiedUserEmail="@user.Email" />

Verified mode switches on as soon as VerifiedUserEmail is non-empty. Leave these unset for anonymous portals and the fields stay editable as normal.

Attachments & camera

Customers can attach files/images to a new request (up to 10 MB each by default). Attachments upload after the ticket is created and appear on the ticket view.

<BeaconHelpCenter BaseUrl="https://your-beacon/api/"
                  PortalKey="pk_live_xxxxxxxx"
                  AllowAttachments="true"
                  MaxAttachmentBytes="10485760" />

Set IsMaui="true" when hosting in a .NET MAUI Blazor Hybrid app to add a Take a photo option that opens the device camera (alongside the normal file picker):

<BeaconHelpCenter ... IsMaui="true" />

The camera/file pickers use the platform's native picker through the BlazorWebView, so the MAUI host must declare the relevant permissions — NSCameraUsageDescription/NSPhotoLibraryUsageDescription on iOS and CAMERA/READ_MEDIA_IMAGES on Android — and request them at runtime. No MAUI dependency is added to your project by this library.

Set AllowAttachments="false" to hide attachments entirely.

Theming

For most apps, PrimaryColor is all you need. For full control, pass a HelpCenterTheme — anything you leave unset keeps its default (or is derived from the primary colour):

@using Beacon.HelpCenter.Theming

<BeaconHelpCenter BaseUrl="https://your-beacon/api/"
                  PortalKey="pk_live_xxxxxxxx"
                  Theme="_theme" />

@code {
    private readonly HelpCenterTheme _theme = new()
    {
        PrimaryColor   = "#0d9488",
        PageBackground = "#f7faf9",
        GradientAngle  = 135,
        CardRadius     = "18px",
        FontFamily     = "'Inter', sans-serif",
    };
}

Every theme value is emitted as a CSS custom property (--bk-*) on the component's root element, so derivation only applies to hex inputs — you can pass any valid CSS colour (rgb(...), named colours, etc.).

Component parameters

Deep links

The component navigates internally and needs no router. If you want real URLs (e.g. so a confirmation email can link straight to a ticket), give it a page in your host app and forward the route/query values:

@page "/help/ticket/{Id}"

<BeaconHelpCenter BaseUrl="https://your-beacon/api/"
                  PortalKey="pk_live_xxxxxxxx"
                  InitialTicketId="@Id"
                  InitialTicketToken="@Token" />

@code {
    [Parameter] public string Id { get; set; } = "";
    [SupplyParameterFromQuery] public string? Token { get; set; }
}

Pair this with TicketLinkFormat="https://app.me/help/ticket/{id}?token={token}" so the success screen shows the customer a link they can save.

What it talks to

All requests are anonymous, public endpoints — safe to expose to end users:

• GET /public/portal/{portalKey} — resolve the portal / app name
• GET /public/kb/categories — knowledge-base categories
• GET /public/kb/folders — knowledge-base folders (one level under categories)
• GET /public/kb/articles and /public/kb/articles/{id} — knowledge base
• POST /public/kb/articles/{id}/feedback — article helpful/not-helpful
• POST /public/tickets — submit a request
• GET|POST /public/tickets/{id}… — track, reply, rate (token-gated)

License

MIT.