Integrer Henvend på nettstedet ditt

Den normale integrasjonen trenger tre ting. Du trenger ikke bygge eller style selve samtalegrensesnittet.

<script
  src="https://henvend.vercel.app/widget.js"
  data-widget-key="YOUR_WIDGET_KEY"
  async>
</script>

• Kopier widgetnøkkelen fra Innstillinger → Widget i Henvend.
• Legg inn nettstedets eksakte opprinnelse under Tillatte nettsteder.
• Lim inn script-taggen globalt, normalt rett før avsluttende body-tag.

Loaderen finner nøkkelen i data-widget-key og bruker opprinnelsen til scriptfilen som Henvend-endepunkt.

1. 1

   Nettleseren laster widget.js fra den konfigurerte Henvend-adressen.

2. 2

   Henvend validerer widgetnøkkel og eksakt nettstedopprinnelse før konfigurasjonen returneres.

3. 3

   Organisasjonens tekst, farger, plassering og tilgjengelighetsstatus lastes automatisk.

4. 4

   Widgeten oppretter en privat, anonym kundesesjon først når en ny henvendelse sendes.

Widgeten rendres i Shadow DOM. Det isolerer Henvends stil fra nettstedets CSS, og nettstedet skal ikke gjenskape eller overstyre widgetgrensesnittet.

Kundens anonyme sesjon og aktive samtalereferanse lagres lokalt i samme nettleser og nettstedopprinnelse. Det gjør at samtalen kan fortsette etter navigasjon eller ny innlasting på samme enhet.

Når widgeten deaktiveres i Henvend, fjernes åpneknappen og nye henvendelser avvises. Historiske samtaledata slettes ikke av denne handlingen.

En opprinnelse består av protokoll, vertsnavn og eventuell port. Henvend sammenligner den eksakte Origin-verdien fra nettleseren.

https://example.no
https://www.example.no
http://localhost:3000

http://example.no
https://example.no/shop
https://example.no?preview=1

• https://example.no og https://www.example.no er forskjellige opprinnelser og må legges inn hver for seg dersom begge brukes.
• Produksjonsnettsteder må bruke HTTPS. HTTP godtas bare for localhost, 127.0.0.1 og lokal IPv6 under utvikling.
• Ikke ta med sti, spørring, fragment eller innloggingsinformasjon. Bruk bare opprinnelsen.
• Legg til hvert faktisk produksjons-, underdomene- og utviklingsopphav som skal laste widgeten.

Henvend.setContext() knytter det kunden ser på til en ny henvendelse. type er en beskrivende, bransjenøytral verdi – for eksempel property, product, venue, vehicle eller listing.

Henvend.setContext({
  type: "property",
  externalId: "B304",
  title: "Leilighet B304",
  price: "4 790 000 kr",
  url: window.location.href
});

Henvend.setContext({
  type: "product",
  externalId: "product-123",
  title: "Produktnavn",
  url: window.location.href,
  imageUrl: "https://www.example.no/images/product-123.jpg"
});

Kontekstobjektet kan bare inneholde feltene i tabellen. Ukjente felt, manglende påkrevde verdier eller ugyldige grenser gjør konteksten ugyldig.

Den flytende åpneknappen er ikke den eneste inngangen. En side kan åpne widgeten fra en kontekstuell knapp og sende konteksten i samme kall.

<button type="button" id="ask-about-item">
  Spør om dette objektet
</button>

<script>
  document.getElementById("ask-about-item").addEventListener("click", () => {
    const openHenvend = () => Henvend.open({
      context: {
        type: "listing",
        externalId: "B304",
        title: "Eksempelobjekt B304",
        url: window.location.href
      }
    });

    if (window.Henvend) openHenvend();
    else window.addEventListener("henvend:ready", openHenvend, { once: true });
  });
</script>

Henvend.open() kan kalles uten argumenter, eller med et objekt som inneholder context og/eller routingKey. Alternativt kan du kalle setContext() og setRoutingKey() før open().

Ruting er valgfritt og uavhengig av kontekst. Bruk en offentlig rutingnøkkel som er opprettet i organisasjonens rutinginnstillinger.

Henvend.setRoutingKey("sales");

// Når brukeren forlater denne delen av nettstedet:
Henvend.clearRoutingKey();

1. 1. En gyldig, aktiv rutingnøkkel satt på siden.
2. 2. Det aktive standardteamet som er konfigurert for widgetintegrasjonen.
3. 3. Generell / ikke rutet organisasjonsflyt dersom ingen av de to første gir et team.

En rutingnøkkel kan være opptil 80 tegn og bruker små bokstaver, tall og enkle bindestreker, for eksempel sales eller project-harbour.

Rutingnøkler er offentlige identifikatorer, ikke hemmeligheter. De løses bare innen organisasjonen som allerede er validert av widgetnøkkel og opprinnelse. Nettleseren kan ikke velge organisasjon, team eller medarbeider med en UUID.

Det kanoniske globale grensesnittet er window.Henvend. Metodenavn og tekniske verdier er de samme uansett hvilket språk Henvend-grensesnittet bruker.

Så snart widget.js er kjørt, oppretter loaderen et synkront Henvend-grensesnitt. Kall køes mens widgetkonfigurasjonen lastes. Kode som kan kjøre før selve scriptfilen er lastet, bør vente på scriptets load/onReady eller henvend:ready.

Når widgeten er initialisert, sender nettleseren hendelsen henvend:ready på window.

En SPA laster normalt widget.js bare én gang. Oppdater derfor kontekst og ruting eksplisitt når gjeldende objekt eller nettsteddel endres.

function showListing(listing) {
  Henvend.setContext({
    type: "listing",
    externalId: listing.id,
    title: listing.title,
    price: listing.price,
    url: window.location.href
  });
  Henvend.setRoutingKey("sales");
}

function leaveListing() {
  Henvend.clearContext();
  Henvend.clearRoutingKey();
}

Kall clearContext() og clearRoutingKey() når brukeren forlater en kontekstuell/rutet del. Dette hindrer at en senere ny samtale arver opplysninger fra forrige skjerm. En allerede opprettet samtale forblir uendret.

next/script kan laste widgeten etter hydrering. onReady kjører i en klientkomponent når scriptet er klart og ved senere remontering.

"use client";

import Script from "next/script";
import { useEffect, useState } from "react";

declare global {
  interface Window {
    Henvend?: {
      setContext: (context: unknown) => Promise<void>;
      clearContext: () => Promise<void>;
    };
  }
}

export function HenvendWidget({ listing }) {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    if (!ready) return;

    if (listing) {
      void window.Henvend?.setContext({
        type: "listing",
        externalId: listing.id,
        title: listing.title,
        url: window.location.href
      });
    } else {
      void window.Henvend?.clearContext();
    }

    return () => {
      void window.Henvend?.clearContext();
    };
  }, [listing, ready]);

  return (
    <Script
      src="https://henvend.vercel.app/widget.js"
      data-widget-key="YOUR_WIDGET_KEY"
      strategy="afterInteractive"
      onReady={() => setReady(true)}
    />
  );
}

• onReady og tilgang til window krever en Client Component.
• Kall API-et i onReady eller i en effekt som først kjører etter at scriptet er klart.
• Oppdater eller nullstill kontekst når route- eller produktdata endres. Ikke forvent at scriptet lastes på nytt ved klientnavigasjon.

Legg loaderen inn globalt via tema/mal, en sikker kodeplassering i nettstedbyggeren eller nettstedets egen scriptfunksjon. Henvend krever ikke en bestemt tredjepartsplugin.

• Last widgetscriptet én gang globalt.
• La objekt- eller produktmalen skrive ut setContext() med data for den aktuelle siden.
• Kode CMS-verdier korrekt som JavaScript/JSON. Ikke sett sammen ubeskyttet brukergenerert tekst i en script-tag.
• Registrer henvend:ready-lytteren før den asynkrone loaderen for å unngå en lastingskonkurranse.

<!-- Skriv ut dette fra objektmalen med sikkert kodede CMS-verdier. -->
<script>
  window.addEventListener("henvend:ready", function () {
    Henvend.setContext({
      type: "listing",
      externalId: "LISTING_ID",
      title: "LISTING_TITLE",
      url: window.location.href
    });
  }, { once: true });
</script>

<script
  src="https://henvend.vercel.app/widget.js"
  data-widget-key="YOUR_WIDGET_KEY"
  async>
</script>

Widgeten henter organisasjonens lagrede oppsett automatisk. Nettstedutvikleren skal normalt ikke endre grensesnittet.

• Åpneknapp, overskrifter, samtaletekst og kontaktoppfordringer styres fra Innstillinger → Widget.
• Farger, plassering og avrunding styres fra samme sted og forhåndsvises før lagring.
• Åpningstider, tidssone og tilgjengelighetstekst beregnes av Henvend fra organisasjonens innstillinger.
• Ikke bruk CSS-overstyringer. Shadow DOM isolerer widgeten, og strukturerte Henvend-innstillinger er den støttede tilpasningen.

Test hele flyten på en separat utviklingsopprinnelse før produksjonslansering.

1. Legg til den eksakte utviklingsopprinnelsen i Henvend.
2. Last widgetscriptet med riktig offentlig nøkkel.
3. Bekreft at åpneknappen vises og kan åpnes.
4. Send en testhenvendelse som kunde.
5. Bekreft at riktig organisasjon og kvalifiserte medarbeidere mottar den.
6. Svar fra arbeidsområdet og bekreft at svaret vises i widgeten.
7. Kontroller kontekstkortet for en kontekstuell side.
8. Kontroller team/ruting med en gyldig rutingnøkkel.
9. Test generell flyt etter clearContext() og clearRoutingKey().
10. Test mobilvisning og tastaturnavigasjon.
11. Last siden på nytt i samme nettleser og bekreft at den private kundesamtalen fortsetter.

Bruk nettleserens Console- og Network-panel til å se om loaderen eller forespørsler feiler, men ikke del kundetokens, Authorization-headere eller private samtaledata i supportsaker.

Nettsteder med streng CSP må tillate de ressursene widgeten faktisk bruker.

• script-src må tillate den konfigurerte Henvend-opprinnelsen som leverer widget.js.
• connect-src må tillate Henvend-opprinnelsen og Henvends distribusjonsspesifikke Supabase HTTPS- og WSS-endepunkter for anonym sesjon, data og sanntidssvar.
• img-src må tillate vertene som nettstedet selv sender i imageUrl dersom kontekstbilder brukes.