Data Feeds

Oversigt #

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

Vi understøtter to forskellige varianter 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 rådighed for at sikre og importere 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 ideelt 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 #

Ukontrollerede null værdier er en sikker vej for fejl over tid. Hvis en attribut ikke eksisterer for et givet 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 strings. Du skal altid vælge é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 kan altså 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 krævede felter for typen, for at Clerk.io’s AI kan fungere korrekt, og de kan desuden indeholde 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 overordnet produkt, og inkludere attributter, der beskriver varianterne som color, size, material osv.

Herunder ses de krævede felter samt eksempler på valgfrie felter, der 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
  }
]

Bevar produkter uden indeksering #

For nogle opsætninger kan du ønske at gemme produkter i Clerk.io’s database uden at vise dem i nogen resultater.

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

For at gøre dette, tilføj attributten index: false til produktobjekter, der skal bevares uden at blive indekseret. Clerk vil derefter bruge salgsdataens historik for at vise resultater, men de vil aldrig blive vist i nogen API-kald.

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

Kategorier #

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

Herunder ses de krævede felter og eksempler på valgfrie felter, der 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, hvis de fjernes fra feedet. De skal normalt kun sendes ved 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 dokumentationen her.

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

Herunder ses de krævede felter og 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. Attributterne sammenflettes så med kundens email eller customer ID fra ordrer og danner en samlet kundeprofil til brug for Audience-segmentering.

Herunder ses de krævede felter og eksempler på valgfrie felter, der 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 omfatter generelt alle typer e-handelsindhold, der ikke klassificeres som produkt eller kategori. Det kan fx være artikler, blogindlæg, landingssider, brandsider og andre typer skrevne tekster.

Herunder ses de krævede felter og eksempler på valgfrie felter, der 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"]
 }
]

Fleresprogede feeds #

Clerk.io fungerer bedst, når du opretter separate Stores for hvert sprog. Hver Store kan opsættes med indholdets sprog, hvilket gør, at Search forstår grammatik og stavefejl væsentligt bedre.

Kunder fra forskellige regioner eller lande har ofte forskellige præferencer og søgemønstre, hvilket betyder, at det også fungerer bedst at adskille ordredata i forskellige Stores.

Alternativt kan du lave 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, også hvis indholdet er det samme, for at gøre dem søgbare for sproget.

Når der foretages API-kald, inkludér parameteren language og tilsvarende 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 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 nøjagtige navn. Vi understøtter i øjeblikket 54 sprog. Hvis dit sprog ikke er på listen nedenfor, vælg et beslægtet sprog eller blot “english”. Det vil stadig virke, men grammatisk neutralisering i Search vil være mindre effektiv.

• afrikaans
• albansk
• arabisk
• armensk
• azerbajdsjansk
• baskisk
• hviderussisk
• bengali
• bosnisk
• bulgarsk
• catalansk
• 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
• malaysisk
• norsk
• persisk
• polsk
• portugisisk
• rumænsk
• russisk
• serbisk
• slovakisk
• slovensk
• spansk
• svensk
• filipino
• thai
• tyrkisk
• ukrainsk
• urdu
• vietnamesisk

Flere feeds #

Dette er den anbefalede tilgang, da det er effektivt for din server og giver maksimal kontrol.

Denne tilgang bygger på, at du laver 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 gør det muligt at paginere resultater ved at kode dit feed, så det accepterer 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 importør kan indstilles til at sende disse parametre til din feedkode. Du vælger blot det antal objekter, du vil hente pr. side.

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

{{limit}} vil indeholde det tal, du vælger i importørindstillingerne. {{offset}} starter på 0 ved første kald, og vokser herefter baseret på limit.

F.eks.

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

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

URL #

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

Inkrementer #

Når du bruger denne funktion, vil Clerk.io stoppe med at slette objekter ved import, så du skal bruge CRUD API-kald for at fjerne objekter fra Clerk.io’s database.

Løsningen med flere feeds understøtter den valgfrie funktion kun at sende de data, der er ændret siden et valgt antal dage, i stedet for at sende alle data hver gang.

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

Derefter skal du tilføje et antal dage i feltet mærket Incremental time {{modified_after}} som findes i Clerk.io’s importørindstillinger.

Dette betyder, at Clerk.io’s importør beholder alle data i databasen og kun opdaterer de objekter, der er inkluderet i feeds.

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

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

X-Clerk-Authorization: Bearer THE_TOKEN

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

Enkel feed #

Parametre #

Udover selve objekterne 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 afgøre, om nye data skal hentes.
• strict: Når true, importeres alle data som de er. Når false forsøger Clerk.io at rydde op i dataene, fx ved at fjerne dublerede produkter eller kategorier og konvertere teksttal til integers eller floats.

Eksempel på feed #

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

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

Sikkerhed #

Dine data er ekstremt forretningsfølsomme, så sikkerhed er førsteprioritet!

Vi anbefaler, at JSON-feedet kun accepterer en SSL-krypteret forbindelse og gerne bruger HTTP Authentication.

Derudover tilbyder Clerk et ekstra lag sikkerhed, så du kan bekræfte at feedanmodningen faktisk stammer fra en betroet kilde (dvs. os).

Systemet bygger på en delt hemmelighed; en Private API-nøgle, der kan oprettes i my.clerk.io under Developers > API Keys.

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

salt er blot en tilfældig streng, der bruges til at “salte” hashfunktionen, mens hash er et SHA512-hash, der beregnes ud fra Private API-nøglen på følgende måde:

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

Et eksempel på request 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 anmodningen, kan du lave samme beregning på din server og sammenligne hash-værdierne for at bekræfte, at de er ens, og at anmodningen dermed stammer fra Clerk.io