Widget SDK

Quickstart

Two lines. Paste the script once in your site layout, then drop the element wherever you want the form.

<!-- once, in your site layout -->
<script async src="https://digitalarborist.app/widget/v1/da-widget.js"></script>

<!-- wherever the form belongs -->
<da-quote-form widget-key="YOUR_KEY"></da-quote-form>

That is a working lead form: it collects the contact details needed to create a real customer account, checks for an existing customer, and asks a returning one which of their properties the request is for instead of making them retype an address.

Installing the SDK

The script tag

<script async src="https://digitalarborist.app/widget/v1/da-widget.js"></script>

Content Security Policy

If your site sends a CSP, the SDK needs to be allowed to load and to reach the API:

script-src  https://digitalarborist.app;
connect-src https://digitalarborist.app;

No unsafe-inline and no unsafe-eval are required.

Verifying it loaded

// In the browser console on your page:
window.DAWidget.version          // → "0.1.0"
window.DAWidget.components()     // → ["da-quote-form","da-visit-track","da-portal"]

If window.DAWidget is undefined, the script did not execute — check the Network tab for a blocked request, and check for a CSP or content blocker before looking anywhere else.

Your widget key

widget-key is public by design. It goes in your page source and anyone can read it. It selects which firm a request belongs to — it authenticates nobody.

• Committing it to a public repo or a client bundle is fine and expected. It is not a secret and never was.
• Every widget request is treated as anonymous, which is why responses are deliberately minimal. The duplicate check returns property addresses you can click — never customer names, emails or phone numbers.
• There is no self-service key rotation yet. Changing a key is a manual operation on our side. Worth knowing before you plan around it.

<da-quote-form> — quote form

The component your lead flow depends on. It collects what is needed to create a real customer account, runs duplicate detection, and routes a returning customer to a property picker.

<da-quote-form
  widget-key="YOUR_KEY"
  heading="Request an estimate"
  intro="Tell us what you need and we'll get back to you."
  service="Pruning"
  contact="phone"
  phone="(512) 555-0100"
></da-quote-form>

Attributes

What it asks the visitor for

Texting consent is per-number and three-valued — ticked, unticked, or never asked. The checkbox always renders, so an unticked box records a real "no" rather than an unknown. Choosing Text message as the preferred contact method without ticking at least one number is refused inline, because the API refuses it too: a preference we cannot route is worse than no preference.

Sending your own data

The SDK has no service list and will not get one. A list of services hard-coded into a shared component goes stale the moment you change your offering, and is wrong by construction for every other firm. You own that data. There are two ways to hand it over.

Simple — one service page, one attribute

<da-quote-form widget-key="YOUR_KEY" service="Removal"></da-quote-form>

Rich — you collected structured data yourself

Set the message property (a property, not an attribute — it holds structured data):

const form = document.querySelector('da-quote-form');

form.message = {
  // Overrides the `service` attribute. Free text — your vocabulary, not ours.
  services: 'Removal, Pruning',

  // Anything else you collected. Stored on the request and rendered for staff.
  payload: {
    source: 'tree-selector',
    summary: 'Privacy screen · 3 trees · back yard',
    sections: [
      { label: 'Species picked', items: [{ label: 'Live Oak', value: 'no caveat' }] },
      { label: 'Site',           items: [{ label: 'Irrigation', value: 'Existing zone' }] },
    ],
  },

  // Prefills step 2. Also the ONLY source of coordinates.
  address: {
    street: '900 Guard St', city: 'Austin', state: 'TX', zip: '78704',
    lat: 30.245, lng: -97.77,
  },
};

The payload shape above (source, summary, sections) renders as labelled prose in the staff email and the office dashboard. Any other shape still renders, generically — but map your internal codes to display strings first. "soil_depth": "unknown" reads to staff as we failed to ask; { label: 'Soil depth', value: "Don't know" } reads as an answer.

<da-portal> — client portal

<da-portal widget-key="YOUR_KEY" heading="My Account"></da-portal>

Tabs: Overview, Invoices, Documents, Properties, Tree Care, Contact, Account, Help. Login supports a password or a magic link — if the page loads with ?token=… it signs the customer in automatically and cleans the URL. If the page also loads with ?payJob=<jobId> (a hosted payment link your staff emailed), the customer lands directly on that job's Pay view instead of the dashboard — no extra click needed.

Paying an invoice

The Invoices tab shows only the payment methods that are both connected AND enabled for that specific invoice — never a button that can't work. Depending on what you've connected, a customer may see QuickBooks pay-by-bank / pay-by-card straight from your QuickBooks-hosted payment page (genuinely off your website — Intuit hosts it, with your convenience fee disclosed first if you've turned one on), and/or Stripe one-time pay-by-card / pay-by-bank, confirmed in-page through Stripe's own hosted payment element. A Stripe-only account never shows a QuickBooks button, and vice versa. A "Saved cards" section also lets a customer keep a card on file (Stripe) for your office to charge later; there is no self-serve one-click charge from a saved card. If nothing is payable yet for an invoice, the customer sees a "contact us" message instead of a dead button.

Tree Care

If a customer is enrolled in one of your recurring tree-care programs at any of their properties, this tab lists the services included in that program (name and short description — never a plan-tier label). If they aren't enrolled anywhere, it shows a short invitation message you configure yourself (Tools → Configuration), with an optional link to a page of yours. Leave both blank and the tab shows a plain "nothing configured yet" message instead of appearing broken.

Properties, contact and account

The Properties tab lists each property a customer has with you, with a drill-down into the jobs and tree inventory recorded there. The Contact tab lets a customer send a message or request a quote (optionally naming one of their properties) — both land in your usual staff notification queue. The Account tab lets a customer edit their own name, email, phone and mobile, and set their own password — a real forgot-password flow: a customer signed in the normal way sees "Change password" (needs the current one), while a customer who signed in via an emailed link sees "Set a new password" with no current password required, since the link itself already proved it's them. Either way, their other signed-in devices are signed out.

The Help tab

An AI assistant that answers your customers' "how do I…" questions about the portal, in your firm's voice. It knows how the portal works; it does not look up a customer's invoices, jobs or records, so it points them at the right tab — or at you — instead of quoting figures it cannot verify.

• It tells customers how to reach you using your CRM record — firm name, phone and admin email. Keep those fields current, because that is what your customers will be told to call.
• Fair-use capped at 30 messages per customer per hour. Over the cap the customer is asked to try later or contact your office; nothing breaks.
• It only exists while signed in, and it is a tab rather than a floating bubble — nothing of ours covers your page, and it will not collide with a chat widget you already run.

<da-visit-track> — campaign attribution

<!-- put this in your site LAYOUT so it runs on every page -->
<da-visit-track widget-key="YOUR_KEY"></da-visit-track>

Renders nothing and takes no space. It records the visit, its referrer and any UTM parameters, then hands a visit ID to the quote form so a submitted lead is attributed to the campaign that produced it. It records one row per pageview, which is what makes "which marketing spend produced approved work?" answerable.

Failures are silent by design. A tracking problem must never cost a lead, so nothing about this can block or break a submission.

Optional: version observability

The element always sends its own SDK version automatically — nothing to configure. If you want us to see which version of your integration is running, set host-version:

<da-visit-track widget-key="YOUR_KEY" host-version="1.4.0"></da-visit-track>

Purely observational, never required.

Optional: GA4 correlation

If you run Google Analytics 4 on the same page (a gtag.js install — load order relative to this element doesn't matter), set ga4-id to your GA4 measurement id and the element will correlate its visit with GA4's own client_id/session_id:

<da-visit-track widget-key="YOUR_KEY" ga4-id="G-XXXXXXXXXX"></da-visit-track>

You set this yourself, on your own page — the widget does not fetch it from anywhere. If your Digital Arborist CRM account also has a GA4 Measurement ID configured in Firm Settings → Integrations, that's a separate copy used only for the CRM's own dashboard reporting link; enter the same id in both places so they point at the same property.

Events

Every component dispatches da:-prefixed CustomEvents. They bubble and cross the shadow boundary, so you can listen on document.

document.addEventListener('da:success', (e) => {
  gtag('event', 'generate_lead', { method: e.detail.mode });
});