Adressefelt til checkout og formularer

Feltet ovenfor er den samme fil, som din side indlæser. På denne side kører den uden nøgle mod vores demo-endpoints; på din side bruger den din offentlige nøgle. Forslagene er de samme.

Kom i gang

1. 1

   Opret en offentlig nøgle

   Under Nøgler i dashboardet vælger du Offentlig og skriver de domæner, feltet skal virke på, fx butik.dk og www.butik.dk. Tilføj localhost:3000 (eller den port, du udvikler på), hvis du vil prøve lokalt. Brug en testnøgle (gf_pub_test_), mens du bygger.

2. 2

   Indsæt scriptet

   Læg tagget før </body> eller i <head> med defer. data-felt er en CSS-selektor for det felt, kunden skriver adressen i; data-postnr og data-by peger på felterne, der skal udfyldes.

   htmlKopiér

   <script
     src="https://grundfast.dk/widget/v1/grundfast-adresse.js"
     defer
     data-key="gf_pub_live_..."
     data-felt="#adresse"
     data-postnr="#postnr"
     data-by="#by"
   ></script>

3. 3

   Prøv det

   Skriv en adresse. Vises der ingen forslag, står årsagen i browserens konsol — se Fejlfinding.

Kan du ikke sætte en selektor på scriptet, kan du i stedet markere selve feltet. Her skal indstillingerne have data-gf- foran, så de ikke kan forveksles med temaets egne attributter:

<input id="adresse" name="adresse" data-grundfast-adresse
       data-gf-postnr="#postnr" data-gf-by="#by">

Felter, der først dukker op senere — en checkout, der tegnes af JavaScript, eller et trin i en formular — får feltet på, når de vises. Guides til de enkelte platforme: WooCommerce, Shopify og alle guides om adresser.

Offentlige nøgler

En almindelig nøgle (gf_live_, gf_test_) er hemmelig og hører til på en server. En offentlig nøgle (gf_pub_live_, gf_pub_test_) er lavet til at stå i en webside, hvor alle kan læse den. Derfor kan den langt mindre:

• Kun fra dine domæner. Kaldet skal komme fra en side på et af nøglens tilladte domæner. API’et læser browserens Origin-header (eller Referer, hvis Origin mangler). Et kald uden nogen af dem afvises.
• Kun adresseopslag. Nøglen åbner adressesøgning og autocomplete, opslag af én adresse, datavask af én adresse og postnumre — alle som GET. Registre, batch, eksport og din konto kræver en hemmelig nøgle.
• En grænse pr. besøgende. Ud over planens burst-grænse får hver IP-adresse højst 120 kald i minuttet med samme nøgle, så én, der kopierer nøglen, ikke kan bruge hele din kvote på et øjeblik.

Et domæne uden port gælder kun standardporten. * alene og *.dk afvises. Et domæne med æ, ø eller å skrives i den form, browseren sender: xn---formen (punycode). Ændrer du listen, slår det igennem inden for et halvt minut.

Origin-tjekket stopper andre websites i at bruge din nøgle fra deres besøgendes browsere. Et script uden for en browser kan skrive en hvilken som helst Origin; det er grænsen pr. IP-adresse og de få endpoints, der begrænser skaden. Mistænker du misbrug, så tilbagekald nøglen og opret en ny — det tager et minut at skifte den i scriptet.

Nøglen sendes som ?token= i et almindeligt GET, så browseren ikke skal lave et CORS-preflight først. Vil du kalde endpoints selv med en offentlig nøgle, virker Authorization: Bearer også; svaret åbnes for dit domæne med Access-Control-Allow-Origin.

const res = await fetch(
  'https://api.grundfast.dk/v1/adresse/search?per_side=8&q=' +
    encodeURIComponent('Jægersborggade 10') +
    '&token=gf_pub_live_...'
);
const { results } = await res.json();

Indstillinger

Alle indstillinger er data--attributter på script-tagget. På et markeret felt skrives de med data-gf- foran og gælder kun det felt. Felt-indstillingerne er CSS-selektorer; de slås først op i feltets egen formular.

Hændelsen, når en adresse er valgt

Når kunden har valgt, sender feltet hændelsen grundfast:adresse. Den bobler op gennem siden, så du kan lytte på document eller formularen. detail er hele adressen:

document.addEventListener('grundfast:adresse', (e) => {
  const a = e.detail;
  console.log(a.betegnelse, a.bfe_nummer);
});

{
  "betegnelse": "Jægersborggade 10, st. tv, 2200 København N",
1  "adresselinje": "Jægersborggade 10, st. tv",
  "vejnavn": "Jægersborggade",
  "husnr": "10",
  "etage": "st",
  "doer": "tv",
  "postnr": "2200",
  "postnrnavn": "København N",
  "kommunekode": "0101",
2  "adgangsadresse_id": "0a3f507a-a100-32b8-e044-0003ba298018",
2  "adresse_id": "0a3f509f-1325-32b8-e044-0003ba298018",
3  "bfe_nummer": 9866621,
  "koordinat": { "lon": 12.5449906, "lat": 55.6921031 }
}

Fra JavaScript

I en app, der selv tegner sine felter, kobler du feltet på med GrundfastAdresse.attach og fjerner det igen med destroy(). Indstillingerne er de samme som attributterne, skrevet i camelCase, og felterne kan være elementer i stedet for selektorer.

const felt = GrundfastAdresse.attach(document.querySelector('#adresse'), {
  key: 'gf_pub_live_...',
  postnr: '#postnr',
  by: '#by',
  onSelect: (adresse) => gemPaaOrdren(adresse),
});

// Når formularen forsvinder:
felt.destroy();

Værdierne skrives, som hvis kunden selv havde tastet dem: feltets egen setter og bagefter input- og change-hændelser. Derfor opdaterer React-, Vue- og blok-checkouts deres tilstand uden ekstra kode.

Udseende

Forslagslisten arver skrifttypen fra siden. Farver og hjørner styres med CSS-variabler, som du sætter på :root:

:root {
  --gf-adr-bg: #fff;          /* listens baggrund */
  --gf-adr-fg: #1a1a1a;       /* tekst */
  --gf-adr-border: #c8c8c8;
  --gf-adr-active: #eef3ff;   /* forslaget, der er markeret */
  --gf-adr-active-fg: inherit;
  --gf-adr-radius: 6px;
}

Vil du style alt selv, så sæt data-css="false" og brug klasserne .gf-adr-liste (listen), .gf-adr-valg (et forslag; det markerede har aria-selected="true") og .gf-adr-note (overskriften i trinnet med etage og dør).

Feltet er en tilgængelig combobox: piletasterne flytter i listen, Enter vælger, Escape lukker, og en skærmlæser får antallet af forslag læst op. Enter sender stadig formularen, når intet forslag er markeret.

Versioner og cache

Vil du låse filen med Subresource Integrity, så brug den faste version:

<script
  src="https://grundfast.dk/widget/1.0.0/grundfast-adresse.js"
  integrity="sha384-zgjWtsuGrsYs+BZIp0mG5VEIvkOffWtOKqoxEBZG2u3Zbu4cnV9DVPhiFd+o/+ia"
  crossorigin="anonymous"
  defer
  data-key="gf_pub_live_..."
  data-felt="#adresse"
></script>

Fejlfinding

Feltet blokerer aldrig formularen: fejler et opslag, lukker listen, og kunden kan skrive adressen selv. Årsagen skrives én gang i browserens konsol med [grundfast-adresse] foran.

Har din side en Content-Security-Policy, skal script-src tillade https://grundfast.dk og connect-src tillade https://api.grundfast.dk. Widgetten indsætter et lille stylesheet; tillader din style-src ikke det, så sæt data-css="false" og style klasserne selv. Fejlkoderne står samlet under Fejl og statuskoder.