Data Feeds

Oversigt #

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

Vi understøtter to forskellige varianter af feeds:

• Flere filer til forskellige objekter
• En enkelt fil, der indeholder alle objekter

De to løsninger bruger den samme objektstruktur, men har forskellige funktioner til 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, fjerner Clerk.io det fra databasen, når det importeres. Ordrer bliver logget og beholdes i databasen.

Vi anbefaler at generere JSON-feed(s) mindst én gang om dagen, 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ængelig 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 at få fejl til at snige sig ind over tid. Hvis en attribut ikke eksisterer for et givent produkt, kategori eller en ordre, så udelad simpelthen attributten.

ID-værdi typer #

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 være af samme type.

Attributnavne #

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

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

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 påkrævede felter for typen for at Clerk.io’s AI kan fungere korrekt, og de kan valgfrit indeholde ekstra attributter, der findes i e-handelsplatformen.

Produkter #

Hvert objekt repræsenterer et enkelt produkt. Hvis du har konfigurerbare produkter, anbefaler vi, at du kun sender parent-produktet og inkluderer attributter, der beskriver børnene, såsom color, size, material osv.

Nedenfor kan du se de påkrævede felter samt anbefalede felter, 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 #

For nogle opsætninger kan du have behov for at beholde produkter i Clerk.io’s database uden at vise dem i nogen søgeresultater.

Hvis du sælger billetter eller brugte varer, som kun vil være tilgængelige i en periode, før de aldrig kommer tilbage, er det en god idé at bevare historikken for disse produkter, så Clerk kan bruge det til at forbedre resultaterne.

For at gøre dette skal du tilføje den særlige attribut index: false til de produktobjekter, som skal bevares uden at blive indekseret. Clerk vil så bruge salgs-historikken til at vise resultater, men de vil aldrig blive vist ved API-kald.

For andre produkter lader du simpelthen attributten være ude eller sætter den til index: true.

Kategorier #

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

Nedenfor kan du se de påkrævede felter samt eksempler på valgfrie felter, som ofte bruges 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 slettes ikke, når de fjernes fra feedet. De bør generelt kun sendes under den første import og kan derefter fjernes igen for at spare serverkapacitet. De kan slettes via vores CRUD API.

parcels-data kan for nuværende kun synkroniseres via CRUD API. Se dokumentationen her.

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

Nedenfor ser du de påkrævede felter samt valgfrie felter. Det er ikke muligt at sende yderligere attributter for 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 leverede attributter flettes derefter med kundens email eller customer-ID fra ordrer for at danne en samlet kundeprofil, der bruges til Audience-segmentering.

Nedenfor ser du de påkrævede felter samt 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 dækker generelt alle typer e-handelsindhold, som ikke klassificeres som produkt eller kategori. Det kan være artikler, blogindlæg, landingssider, brand-sider og andre typer tekstindhold.

Nedenfor ser du de påkrævede felter samt 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 opsættes med indholdets sprog, hvilket gør Search bedre til at forstå grammatik og stavefejl.

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

Et alternativ hertil er at bygge flersprogede 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 hvis indholdet er det samme, så det er søgbart for sproget.

Ved API-kald skal du inkludere parameteren language og den matchende sprognøgle for at hente de korrekte 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 findes på listen nedenfor, vælg et beslægtet sprog eller blot “english”. Det vil stadig virke, men grammares-neutralisering 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 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.

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 gør det muligt at paginere resultater ved at kode dit feed til at acceptere følgende forespørgselsparametre:

• limit: Antallet af objekter, der 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 din 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 bruge {{limit}} og {{offset}} til at tilføje data som query-parametre.

{{limit}} vil indeholde det tal, du konfigurerer i importørens indstillinger. {{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

Stopebetingelsen 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 muligheden for valgfrit kun at sende de data, der er blevet ændret i et valgt antal dage, i stedet for at sende alle data hver gang.

For at gøre dette, skal du sikre, at dit feed kun returnerer objekter, som er ændret inden for det specificerede antal dage, når forespørgslen indeholder parameteren modified_after.

Tilføj så et antal dage i feltet Incremental time {{modified_after}} i Clerk.io’s importør-indstillinger.

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

For at bruge det antal dage, du har konfigureret, skal du tilføje query-parameteren modified_after til dit feed og inkludere tagget, der indsætter det konfigurerede antal dage. 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 bruger HTTP Authentication, hvis det er muligt.

Derudover kan du fra importørens indstillinger aktivere Token Authentication. Clerk.io vil så inkludere en authorization header i alle HTTP-anmodninger, som du skal verificere, før data returneres:

X-Clerk-Authorization: Bearer THE_TOKEN

Du kan verificere tokenet med et POST-kald 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"}'

Enkelt feed #

Parametre #

Ud over objekterne selv understøtter denne tilgang 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 der skal hentes nye data.
• strict: Når true vil alle data blive importeret som de er. Når false vil Clerk.io forsøge at rydde op i dataene, f.eks. ved at fjerne dubletter af produkter eller kategorier og konvertere strenge med tal til integer eller float.

Eksempelfeed #

{
  "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 Authentication, hvis muligt.

Derudover tilbyder Clerk et ekstra sikkerhedslag, så du kan sikre, at feed-anmodningen kommer fra en betroet kilde (dvs. os).

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

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

salt er bare en tilfældig streng, der bruges til at salte hashfunktionen, mens hash er et SHA512-hash, der beregnes ud fra den private API-nøgle på denne måde:

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

Et eksempel på en anmodning 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 fra forespørgslen kan du lave samme beregning på din server og sammenligne hash-værdierne for at sikre, at de er ens, hvilket bekræfter, at forespørgslen kommer fra Clerk.io