Data Feeds

Oversigt #

Uanset din eCommerce-platform, og om vi har en integration eller ej, kan du altid synkronisere data med Clerk.io gennem en eller flere feeds i JSON-format.

Vi understøtter to forskellige variationer af feeds:

• Flere filer for forskellige objekter
• En enkelt fil der indeholder alle objekter

De to løsninger bruger den samme objektstruktur, men har forskellige funktioner til sikring og import af dem, som er beskrevet i denne vejledning.

Alle objekttyper undtagen ordrer spejles fra feeds til Clerk.io’s database. Hvis du fjerner et objekt fra feedet, vil Clerk.io fjerne det fra databasen, når det importeres. Ordrer bliver logget og gemt i databasen.

Vi anbefaler at generere JSON-feed(s) mindst én gang dagligt, men helst oftere. De kan også genereres on-demand, når Clerk.io’s importør anmoder om dem.

Feed(s) skal være tilgængelige på en URL, der kan tilgås fra Clerk.io’s servere.

https://your-website.com/json-feed.json

Datatyper #

Vi understøtter attributter af typerne: int, float, str, array, bool, dict (objekt).

Null-værdier #

Ubehandlede null-værdier er en sikker måde at få fejl til at snige sig ind over tid. Hvis en attribut ikke eksisterer for et bestemt produkt, kategori eller ordre, skal du blot udelade attributten.

ID-værdityper #

Vi anbefaler kraftigt at bruge heltal som ID’er, men det er også muligt at bruge strenge. Du skal altid holde dig til én type i dit feed, hvilket betyder, at alle ID’er for dine objekter skal være af samme type.

Attribut-navne #

Objektattributter kan kun indeholde alfanumeriske værdier (A-Z, 0-9) og underscores.
En gyldig attributnavn kunne derfor være brand_name, men ikke läbel-mærke

Brug af bindestreger eller specialtegn i attributnavne vil medføre, at de ignoreres under synkronisering.

Objektstruktur #

JSON-feeds består af én liste af objekter, med en række felter, der udgør deres data.

Objekter skal som minimum indeholde de obligatoriske felter for typen for at Clerk.io’s AI kan fungere korrekt, og de kan valgfrit indeholde ekstra attributter, der er tilgængelige på eCommerce-platformen.

Produkter #

Hvert objekt repræsenterer et enkelt produkt. Hvis du har konfigurerbare produkter, anbefaler vi kun at sende forældreproduktet og inkludere attributter, der beskriver børnene, såsom color, size, material, osv.

Nedenfor kan du se de obligatoriske felter samt anbefalede, der ofte bruges af eCommerce-butikker.

Eksempel på JSON #

[
  {
    "id": 135,
    "name": "Lightsaber",
    "description": "Antique Rebel Lightsaber",
    "price": 79995.95,
    "list_price": 99995.95,
    "on_sale": true,
    "image": "https://galactic-empire-merch.com/images/a-r-lightsaber.jpg",
    "url": "https://galactic-empire-merch.com/antique-rebel-lightsaber",
    "brand": "Je'daii",
    "categories": [987, 654],
    "created_at": 1199145600,
    "color": {
      "name": "Emerald",
      "converted_name": "Green",
      "image": "https://galactic-empire-merch.com/images/a-r-lightsaber-emerald.jpg",
      "color_code": "#7CFC00"
    },
    "reviews_amount": 164,
    "reviews_avg": 4.8
  },
  {
    "id": 261,
    "name": "Death Star Deluxe",
    "description": "Death Star - Guaranteed idiot proof",
    "price": 99999999999999.95,
    "list_price": 99999999999999.95,
    "on_sale": false,
    "image": "https://galactic-empire-merch.com/images/death-star.jpg",
    "url": "https://galactic-empire-merch.com/death-star",
    "brand": "Imperial Inc.",
    "categories": [345678],
    "created_at": 1197565600
  }
]

Behold produkter uden indeksering #

For nogle opsætninger ønsker du måske at beholde produkter i Clerk.io’s database uden at vise dem i søgeresultater.

Hvis du sælger billetter eller brugte varer, som kun vil være tilgængelige i en periode, er det en god idé at beholde historikken for disse produkter, så Clerk kan bruge det til at forbedre resultater.

For at gøre dette skal du tilføje det specielle attribut index: false til de produktobjekter, som skal beholdes uden at blive indekseret. Clerk vil da bruge historikken for deres salg til at vise resultater, men de vil aldrig blive vist i nogen API-kald.

For andre produkter undlader du blot attributten eller sætter den til index: true.

Kategorier #

Hvert objekt repræsenterer en enkelt kategori. Clerk.io opbygger et internt kategoritræ baseret på underkategorier, der leveres for hver kategori.

Nedenfor kan du se de obligatoriske felter og eksempler på valgfrie, som ofte bruges af eCommerce-butikker.

Eksempel på JSON #

[
  {
    "id": 1,
    "name": "Imperial Goods",
    "subcategories": [42, 25],
    "url": "https://galactic-empire-merch.com/imperial-goods"
  },
  {
    "id": 42,
    "name": "Tatooine",
    "subcategories": [],
    "url": "https://galactic-empire-merch.com/imperial-goods/tatooine"
  },
  {
    "id": 25,
    "name": "Coruscant",
    "subcategories": [],
    "url": "https://galactic-empire-merch.com/imperial-goods/coruscant"
  }
]

Ordrer #

Ordrer bliver logget og slettes ikke, når de fjernes fra feedet. De skal generelt kun sendes under første import og kan derefter fjernes for at spare serverkapacitet. De kan slettes via vores CRUD API.

Hvert objekt repræsenterer en enkelt ordre. Clerk.io bruger produkt-ID’er og e-mailadresse/kunde-ID i ordrer til at analysere kundeadfærd og identificere trends. Sammen med products er det den vigtigste objekttype.

Nedenfor kan du se de obligatoriske felter og valgfrie felter. For at inkludere pakkedata, tilføj et tracking array til ordren. Send ikke pakker som et separat top-level objekt.

Eksempel på JSON #

[
  {
    "id": 123458,
    "customer": 789,
    "email": "vader@the-death-star.com",
    "products": [{"id":456,"quantity":1,"price":200.00}, {"id":789,"quantity":2,"price":120.00}],
    "time": 1389871120,
    "tracking": [
      {
        "tracking_code": "ABC123",
        "tracking_link": "https://carrier.example/ABC123",
        "status": "SENT",
        "status_text": "Out for delivery"
      }
    ]
 },
  {
    "id": 123456,
    "customer": 456,
    "email": "obi.wan@kenobi.me",
    "products": [{"id":456,"quantity":1,"price":200.00}, {"id":789,"quantity":2,"price":120.00},{"id":123,"quantity":2,"price":60.00}],
    "time": 1389870977
 },
  {
    "id": 123457,
    "customer": "",
    "products": [{"id":789,"quantity":2,"price":120.00}],
    "time": 1389871090
 }
]

Kunder #

Hvert objekt repræsenterer en enkelt kunde. De angivne attributter samles med kundens email eller customer-ID fra ordrer for at oprette én samlet kundeprofil til brug for Audience-segmentering.

Nedenfor kan du se de obligatoriske felter og eksempler på valgfrie, der ofte bruges af eCommerce-butikker.

Eksempel på JSON #

[
  {
    "id": 135,
    "name": "Luke Skywalker",
    "email": "luke@rebels.com",
    "subscribed": true,
    "gender": "male",
    "zip": "1134",
    "is_b2b": "false"
 },
  {
    "id": 165,
    "name": "Leia Organa",
    "email": "leia@royalty.org",
    "subscribed": false,
    "gender": "female",
    "age": 19,
    "interests": ["politics", "outlaws"],
    "is_b2b": true
 }
]

Sider #

Hvert objekt repræsenterer en enkelt side. Sider er generelt alle slags eCommerce-indhold, der ikke klassificeres som et produkt eller en kategori. Det kan være artikler, blogindlæg, landingssider, brandsider og andre typer skrevet indhold.

Nedenfor kan du se de obligatoriske felter og eksempler på valgfrie, der ofte bruges af eCommerce-butikker.

Eksempel på JSON #

[
  {
    "id": 135,
    "type": "cms",
    "url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
    "title": "Open Hours",
    "text": "The main text about our opening hours..."
 },
  {
    "id": 1354,
    "type": "blog",
    "url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
    "title": "New Blog Post",
    "text": "The main text about our opening hours...",
    "keywords": ["blog", "post", "new"]
 }
]

Fler-sproget #

Clerk.io fungerer bedst, når du opretter separate Stores for hvert sprog. Hver Store kan konfigureres med indholdets sprog, hvilket får Search til bedre at forstå grammatik og stavefejl.

Desuden har kunder fra forskellige regioner eller lande ofte forskellige præferencer og søgemønstre, hvilket betyder, at det fungerer bedst at adskille orderdata i forskellige Stores.

Et alternativ til dette er at bygge fler-sprogede JSON-feeds, hvor alle tekstattributter leveres som objekter med sprogkoder som nøgler og deres oversættelser som værdier.

Alle tekstattributter skal have sprog-nøgler, selvom indholdet er det samme, for at gøre dem søgbare på det pågældende sprog.

Når du laver API-kald, skal du inkludere parameteren language og den matchende sprog-nøgle for at hente de korrekte data.

Eksempel på fler-sproget JSON #

[
  {
    "id": 135,
    "name": {
      "english":"Lightsaber",
      "spanish":"Sable de luz", 
      "italian":"Spada laser"
      },
    "description": {
      "english":"Antique Rebel Lightsaber",
      "spanish":"Sable de luz rebelde antiguo",
      "italian":"Antica spada laser ribelle"
      },
    "price": 99995.95,
    "image": {
      "english":"https://galactic-empire-merch.com/images/a-r-lightsaber.jpg",
      "spanish":"https://galactic-empire-merch.com/es/images/a-r-lightsaber.jpg",
      "italian":"https://galactic-empire-merch.com/it/images/a-r-lightsaber.jpg"
      },
    "url": {
      "english":"https://galactic-empire-merch.com/antique-rebel-lightsaber",
      "spanish":"https://galactic-empire-merch.com/es/antique-rebel-lightsaber",
      "italian":"https://galactic-empire-merch.com/it/antique-rebel-lightsaber"
      },
    "brand": "Je'daii",
    "categories": [987, 654],
    "created_at": 1199145600,
    "color": {
      "name": "Emerald",
      "converted_name": "Green",
      "image": "https://galactic-empire-merch.com/images/a-r-lightsaber-emerald.jpg",
      "color_code": "#7CFC00"
    },
    "reviews_amount": 164,
    "reviews_avg": 4.8
 },
  {
    "id": 261,
    "name": {
      "english":"Death Star Deluxe",
      "spanish":"Estrella de la Muerte de lujo", 
      "italian":"La Morte Nera Deluxe"
      },
    "description": {
      "english":"Death Star - Guaranteed idiot proof",
      "spanish":"Estrella de la Muerte: a prueba de idiotas garantizada",
      "italian":"Morte Nera - A prova di idiota garantita"
      },
    "price": 99999999999999.95,
    "image": {
      "english":"https://galactic-empire-merch.com/images/death-star.jpg",
      "spanish":"https://galactic-empire-merch.com/es/images/death-star.jpg",
      "italian":"https://galactic-empire-merch.com/it/images/death-star.jpg"
      },
    "url": {
      "english":"https://galactic-empire-merch.com/death-star",
      "spanish":"https://galactic-empire-merch.com/es/death-star",
      "italian":"https://galactic-empire-merch.com/it/death-star"
      },
    "brand": "Imperial Inc.",
    "categories": [345678],
    "created_at": 1197565600
 }
]

Eksempel på kald #

curl -X GET \
  https://api.clerk.io/v2/recommendations/popular \
  -H 'Content-Type: application/json' \
  -d 'key=your_store_public_key&limit=10&language=italian'

Understøttede sprog #

Sproget skal angives med dets præcise navn. Vi understøtter i øjeblikket 54 sprog. Hvis dit sprog ikke er på listen nedenfor, skal du vælge et beslægtet sprog eller blot “english”. Det vil stadig fungere, men grammatikneutralisering i Search vil være mindre effektiv.

• afrikaans
• albansk
• arabisk
• armensk
• azerbaijansk
• baskisk
• hviderussisk
• bengalsk
• bosnisk
• bulgarsk
• katalansk
• kinesisk
• kroatisk
• tjekkisk
• dansk
• hollandsk
• english
• estisk
• finsk
• fransk
• galicisk
• georgisk
• tysk
• græsk
• hebraisk
• hindi
• ungarsk
• islandsk
• indonesisk
• irsk
• italiensk
• japansk
• koreansk
• lettisk
• litauisk
• makedonsk
• malay
• norsk
• persisk
• polsk
• portugisisk
• rumænsk
• russisk
• serbisk
• slovakisk
• slovensk
• spansk
• svensk
• filippinsk
• thai
• tyrkisk
• ukrainsk
• urdu
• vietnamesisk

Flere feeds #

Dette er den anbefalede metode, da det er effektivt for din server og giver den højeste grad af kontrol.

Med denne metode bygger du individuelle feed-filer for hvert af dine objekter. Dette bruger sync metoden kaldet Clerk.io JSON Feed V2.

Disse understøtter content-type: application/x-ndjson eller application/json.

Hver feed skal indeholde et array af objekter.

URL #

https://awsumstuff.com/feed/products.json

Output #

[
  {
    "id": 135,
    "name": "Lightsaber",
    "description": "Antique Rebel Lightsaber",
    "price": 99995.95,
 },
  ...
]

Paginering #

Dette er en valgfri funktion, der gør det muligt at paginere resultater ved at kode dit feed til at acceptere følgende forespørgselsparametre:

• limit: Antal objekter der skal returneres pr. side.
• offset: Indekset for det første objekt der skal returneres på en side.

Clerk.io’s importør kan konfigureres til at sende disse parametre til dit feed-kode. Du skal blot vælge det antal objekter, du ønsker at hente pr. side.

Når du konfigurerer din feed-URL, kan du derefter bruge {{limit}} og {{offset}} til at tilføje data som forespørgselsparametre.

{{limit}} vil indeholde det tal, du konfigurerer i importørindstillingerne. {{offset}} starter på 0 ved første kald og vokser løbende baseret på limit.

F.eks.

• Kald 1: limit=100&offset=0
• Kald 2: limit=100&offset=100
• Kald 3: limit=100&offset=200

Stoppunktet er, når dit feed returnerer et tomt array.

URL #

https://awsumstuff.com/feed/products.json?limit={{limit}}&offset={{offset}}

Inkrementer #

Bruger du denne funktion, vil Clerk.io ophøre med at slette objekter ved import, så du skal bruge CRUD API-kald for at fjerne objekter fra Clerk.io’s database.

Multi-feed-løsningen understøtter den valgfrie funktion kun at sende data, der er ændret siden et valgt antal dage, i stedet for at sende alle data hver gang.

For at opnå dette skal du sikre, at dit feed er konfigureret til kun at returnere objekter, der er ændret indenfor et angivet antal dage, når forespørgslen inkluderer query-parameteren modified_after.

Dernæst skal du tilføje antal dage i feltet mærket Incremental time {{modified_after}} i Clerk.io’s importør-indstillinger.

Dette får Clerk.io’s importør til at holde alle data i databasen, og kun opdatere de objekter, der er inkluderet i feeds.

For at bruge det antal dage du har sat, skal du tilføje query-parameteren modified_after til dit feed og inkludere tagget der indsætter det antal dage, du har valgt. For eksempel:

https://awsumstuff.com/feed/products.json?modified_after={{modified_after}}&limit={{limit}}&offset={{offset}}

Sikkerhed #

Vi anbefaler, at JSON-feedet kun accepterer en SSL-krypteret forbindelse og anvender HTTP Authentication, hvis muligt.

Derudover kan du fra importørindstillingerne aktivere Token Authentication. Clerk.io vil da inkludere en authorization header på alle HTTP-forespørgsler, som du skal verificere inden du returnerer dataene:

X-Clerk-Authorization: Bearer THE_TOKEN

Du kan verificere token med et POST-kald til token/verify endpoint:

curl -X POST \
  https://api.clerk.io/v2/token/verify \
  -H 'Content-Type: application/json' \
  -d '{"token": "THE_TOKEN", "key": "your_store_public_key"}'

Single Feed #

Parametre #

Ud over selve objekterne understøtter denne metode to ekstra parametre:

• created: Et unix timestamp for hvornår feedet sidst blev opdateret. Clerk.io’s importør bruger dette til at identificere om nye data skal hentes.
• strict: Når true bliver al data importeret som den er. Når false vil Clerk.io forsøge at rense data, f.eks. ved at fjerne duplikatprodukter eller -kategorier, samt konvertere stringifierede tal til heltal eller floats.

Eksempel feed #

{
  "products": [ ... ],
  "categories": [ ... ],
  "orders": [ ... ],
  "customers": [ ... ],
  "pages": [ ... ],

  "config": {
    "created": 1567069830,
    "strict": false
  }
}

Sikkerhed #

Dine data er ekstremt forretningskritiske, så sikkerheden har allerhøjeste prioritet!

Vi anbefaler, at JSON-feed kun accepterer en SSL-krypteret forbindelse og anvender HTTP Authentication, hvis muligt.

Derudover tilbyder Clerk et ekstra lag af sikkerhed, hvor du kan verificere at feed-forespørgslen kommer fra en betroet kilde (altså os).

Systemet er baseret på en delt hemmelighed; en Privat API-nøgle, som kan oprettes i my.clerk.io under Developers > API Keys.

Alle Clerk.io-forespørgsler via HTTP eller HTTPS inkluderer to query-parametre hash og salt.

salt er blot en tilfældig streng brugt til at salte hash-funktionen, mens hash er en SHA512-hash beregnet ud fra den private API-nøgle på følgende måde:

hash = SHA512(salt + private_key + str(int(floor(unix_timestamp() / 100))))

Et eksempel på en forespørgsel kunne være følgende URL:

https://example.com/clerk-product-feed.php?salt=f4Ke...A02X&hash=4DFF...340F

Ved at hente både salt og hash parametrene fra forespørgslen, kan du lave samme beregning på din server og sammenligne hash-værdierne for at bekræfte, at de er ens, hvilket betyder at forespørgslen kommer fra Clerk.io