Data Feeds

Oversigt #

Uanset din e-handelsplatform, 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 varianter af feeds:

• Flere filer til forskellige objekter
• Én fil, der indeholder alle objekter

De to løsninger bruger den samme objektstruktur, men har forskellige funktioner til rådighed for at sikre og importere dem, som er beskrevet i denne guide.

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 ved import. Ordrer bliver logget og beholdes i databasen.

Vi anbefaler at generere JSON-feed(s) mindst en gang om dagen, men gerne oftere. De kan også genereres efter behov, når Clerk.io’s importer anmoder om dem.

Feed(s) skal være tilgængelige på en URL, der er tilgængelig 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 (object).

Null-værdier #

Ukontrollerede null-værdier er en sikker måde, hvorpå fejl kan snige sig ind over tid. Hvis en attribut ikke findes for et bestemt produkt, kategori eller en 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 strings. Du skal altid holde dig til én type i dit feed, hvilket betyder at alle ID’er for dine objekter skal have samme type.

Attributnavne #

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

Brug af bindestreger eller specialtegn i attributnavnene vil medføre, at de ignoreres i synkroniseringen.

Objektstruktur #

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

Objekter skal som minimum indeholde de påkrævede felter for typen for at Clerk.io’s AI fungerer korrekt, og kan derudover indeholde eventuelle ekstra attributter, der findes i e-handelsplatformen.

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 varianterne, såsom color, size, material osv.

Nedenfor kan du se de påkrævede felter og eksempler på valgfrie, som ofte bruges af e-handelsbutikker.

Eksempel 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 #

I visse opsætninger vil du måske gerne beholde produkter i Clerk.io’s database uden at vise dem i nogen resultater.

Hvis du sælger billetter eller brugte varer, der er tilgængelige for en periode, er det en god idé at bevare historikken på disse produkter, så Clerk kan bruge dem til at forbedre resultaterne.

For at gøre dette, tilføj attributten index: false til de produktobjekter, der skal opbevares uden at blive indekseret. Clerk vil herefter bruge historikken over deres salg til at vise resultater, men de vil aldrig blive vist i nogen API-kald.

For andre produkter skal du blot udelade attributten eller sætte den til index: true.

Kategorier #

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

Nedenfor kan du se de påkrævede felter og eksempler på valgfrie, som ofte anvendes af e-handelsbutikker.

Eksempel 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 bliver ikke slettet, hvis de fjernes fra feedet. De behøver som regel kun at blive sendt under den første import og kan derefter fjernes igen for at spare serverkapacitet. De kan slettes via vores CRUD API.

parcels-data kan i øjeblikket kun synkroniseres via CRUD API. Se dokumentation her.

Hvert objekt repræsenterer en enkelt ordre. Clerk.io bruger produkt ID’er og email-adresse/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 påkrævede og valgfrie felter. Det er ikke muligt at sende yderligere attributter med ordrer.

Eksempel 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
 },
  {
    "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 vil blive flettet med kundens email eller kunde-ID fra ordrer for at oprette én samlet kundeprofil til brug for Audience-segmentering.

Nedenfor kan du se påkrævede og eksempler på valgfrie felter, som ofte bruges af e-handelsbutikker.

Eksempel 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 enhver form for e-handelsindhold, der ikke klassificeres som produkt eller kategori. Det kan være artikler, blogindlæg, landingssider, brandsider eller andet tekstindhold.

Nedenfor kan du se påkrævede og eksempler på valgfrie felter, som ofte bruges af e-handelsbutikker.

Eksempel 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"]
 }
]

Flersproget #

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

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

Et alternativ til dette er at bygge flersproget 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, selv om indholdet er det samme, for at sikre at det kan søges frem på det respektive sprog.

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

Eksempel flersproget 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-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, vælg et beslægtet sprog eller blot “english”. Det vil stadig fungere, men grammatikneutralisering i Search vil være mindre effektiv.

• afrikaans
• albanian
• arabic
• armenian
• azerbaijani
• basque
• belarusian
• bengali
• bosnian
• bulgarian
• catalan
• chinese
• croatian
• czech
• danish
• dutch
• english
• estonian
• finnish
• french
• galician
• georgian
• german
• greek
• hebrew
• hindi
• hungarian
• icelandic
• indonesian
• irish
• italian
• japanese
• korean
• latvian
• lithuanian
• macedonian
• malay
• norwegian
• persian
• polish
• portuguese
• romanian
• russian
• serbian
• slovak
• slovenian
• spanish
• swedish
• filipino
• thai
• turkish
• ukrainian
• urdu
• vietnamese

Flere Feeds #

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

Med denne tilgang bygger du individuelle feedfiler for hver af dine objekttyper. Dette bruger sync-metoden kaldet Clerk.io JSON Feed V2.

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

Hvert 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 giver mulighed for at paginere resultater ved at kode dit feed til at acceptere følgende query-parametre:

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

Clerk.io’s importer kan konfigureres til at sende disse parametre til dit feed. Du vælger blot, hvor mange objekter du ønsker at hente pr. side.

Når du konfigurerer din feed-URL, kan du bruge {{limit}} og {{offset}} til at tilføje dataene som query-parametre.

{{limit}} indeholder det antal du indstiller i importindstillingerne. {{offset}} starter på 0 i første kald og stiger 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

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

URL #

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

Inkrementer #

Brug af denne funktion betyder, at Clerk.io stopper 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, hvor kun data, der er ændret siden et givent antal dage, sendes i stedet for at sende alle data hver gang.

For at gøre dette, skal du sikre, at dit feed kun returnerer objekter, der er ændret inden for et bestemt antal dage, når forespørgslen indeholder query-parameteren modified_after.

Dernæst skal du angive et antal dage i feltet Incremental time {{modified_after}} i Clerk.io’s importerindstillinger.

Dette får Clerk.io’s importer til at holde alle data i databasen, og kun opdatere objekter, der er med i feedet.

For at bruge det antal dage du har konfigureret, tilføj modified_after-parameteren til dit feed og indsæt tagget, som indsætter det antal dage du har angivet. 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 bruger HTTP-autentificering, hvis det er muligt.

Derudover kan du fra importerindstillinger aktivere Token Authentication. Clerk.io vil så inkludere en autoriserings-header på alle HTTP-forespørgsler, som du skal verificere, før du returnerer data:

X-Clerk-Authorization: Bearer THE_TOKEN

Du kan verificere tokenet med en POST-forespørgsel til token/verify-endpointet:

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 tilgang to ekstra parametre:

• created: Unix-timestamp for hvornår feedet sidst blev opdateret. Clerk.io’s importer bruger dette til at identificere om der skal hentes nye data.
• strict: Når true vil alle data blive importeret som de er. Når false forsøger Clerk.io at rydde op i dataene, f.eks. ved at fjerne dublerede produkter eller kategorier samt konvertere strenge-numre til integers eller floats.

Eksempel-feed #

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

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

Sikkerhed #

Dine data er ekstremt forretningsfølsomme, så sikkerhed har højeste prioritet!

Vi anbefaler, at JSON-feedet kun accepterer en SSL-krypteret forbindelse og bruger HTTP-autentificering, hvis det er muligt.

Derudover tilbyder Clerk et ekstra lag af sikkerhed ved at lade dig verificere, at feed-anmodningen kommer fra en betroet kilde (dvs. os).

Systemet er baseret på en delt hemmelighed; en Private 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, der bruges til at salte hash-funktionen, mens hash er en SHA512-hash, der beregnes 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ørgsels-URL kan være:

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 anmodningen kommer fra Clerk.io