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, Account. Login supports a password or a magic link — if the page loads with ?token=… it signs the customer in automatically and cleans the URL.

<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.

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 });
});