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 for forskellige objekter
• En enkelt fil, der indeholder alle objekter

De to løsninger bruger den samme objektstruktur, men har forskellige funktioner tilgængelige for sikring og import, 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 forbliver 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 det.

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 (objekt).

Null-værdier #

Ukontrollerede null-værdier er en sikker måde at lade fejl snige sig ind over tid. Hvis en attribut ikke eksisterer for et givent produkt, kategori eller ordre, så undlad blot attributten.

ID-værdityper #

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

Attributnavne #

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

Brug af bindestreger eller specialtegn i attributnavne vil få dem til at blive ignoreret ved synkronisering.

Objektstruktur #

JSON-feeds består af en liste af objekter, med et sæt felter, der udgør deres data.

Objekter skal som minimum indeholde de pågkrævede felter for typen, for at Clerk.io’s AI kan fungere korrekt, og de kan valgfrit indeholde ekstra attributter fra e-handelsplatformen.

Produkter #

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

Nedenfor kan du se de krævede felter og eksempler på valgfrie, der ofte bruges af webshops.

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 ønske at 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 i en periode, men ikke vender tilbage igen, er det en god idé at bevare historikken, så Clerk kan bruge den til at forbedre resultater.

For at gøre dette, tilføj den særlige attribut index: false til produktobjekter, der skal gemmes uden at blive indekseret. Clerk vil derefter bruge deres salgsdatahistorik til resultater, men de vil aldrig blive vist i API-kald.

For andre produkter, så undlad blot attributten eller sæt 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.

Nedenfor kan du se de krævede felter og eksempler på valgfrie, der ofte bruges af webshops.

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 skal generelt kun sendes under 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 e-mailadresse/kunde-ID i ordrer til at analysere kundeadfærd og identificere tendenser. Sammen med products er det den vigtigste objekttype.

Nedenfor kan du se 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 Customer. De angivne attributter flettes med kundens email eller kundens ID fra ordrer for at danne en samlet kundeprofil til brug for Audience segmentering.

Nedenfor kan du se de krævede felter og eksempler på valgfrie, der ofte bruges af webshops.

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 alle typer e-handelsindhold, der ikke klassificeres som produkter eller kategorier. Det kan være artikler, blogindlæg, landingssider, brandsider og andre former for tekstindhold.

Nedenfor kan du se de krævede felter og eksempler på valgfrie, der ofte bruges af webshops.

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

Flersprogethed #

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.

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

Et alternativ er at bygge flersprogede JSON-feeds, hvor alle tekstattributter gives som objekter med sprogkoder som nøgler og oversættelser som værdier.

Alle tekstattributter skal have sprognøgler, selvom indholdet er det samme, for at sikre at de kan søges på det pågældende sprog.

Når du laver API-kald, skal du inkludere parameteren language med sprognøglen 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 det præcise 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 grammatikneutralisering i Search vil være mindre effektiv.

• afrikaans
• albansk
• arabisk
• armensk
• azerbaijani
• baskisk
• belarusisk
• 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
• malay
• norsk
• persisk
• polsk
• portugisisk
• rumænsk
• russisk
• serbisk
• slovakisk
• slovensk
• spansk
• svensk
• filipino
• thai
• tyrkisk
• ukrainsk
• urdu
• vietnamesisk

Flere feeds #

Dette er den anbefalede metode, da den er effektiv for din server og giver maksimal kontrol.

Med denne metode bygger du individuelle feed-filer for hver af dine objekter. Det 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 lader dig paginere resultater ved at kode dit feed, så det accepterer følgende query-parametre:

• limit: Antallet af objekter, der returneres pr. side.
• offset: Indekset for det første objekt, der 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, hvor mange objekter du vil 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}} indeholder tallet, du har indstillet i importørens indstillinger. {{offset}} starter ved 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 #

Hvis du bruger denne funktion, stopper Clerk.io med at slette objekter ved import, så du skal bruge CRUD API-kald til at fjerne objekter fra Clerk.io’s database.

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

For at gøre dette, start med at sikre, at dit feed kun returnerer objekter, der er ændret inden for et angivet antal dage, når anmodningen har query-parameteren modified_after.

Tilføj derefter et antal dage i feltet Incremental time {{modified_after}} i Clerk.io’s importørindstillinger.

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

For at bruge det antal dage, du har valgt, tilføj parameteren modified_after til din feed og inkluder tagget, der indsætter antallet af 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-krypterede forbindelser og bruger HTTP Authentication om muligt.

Derudover kan du aktivere Token Authentication fra importørindstillingerne. Clerk.io vil så inkludere et authorisation header i hver HTTP-anmodning, som du skal verificere, før du returnerer data:

X-Clerk-Authorization: Bearer THE_TOKEN

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

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 selve objekterne understøtter denne metode to ekstra parametre:

• created: Et unix timestamp, der angiver, 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 importeres alle data, som de er. Når false forsøger Clerk.io at rydde op i dataene, f.eks. ved at fjerne dubletter og konvertere strengnumre til integers eller floats.

Eksempel-feed #

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

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

Sikkerhed #

Dine data er yderst forretningskritiske, så sikkerhed har højeste prioritet!

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

Derudover tilbyder Clerk et ekstra sikkerhedslag ved at give dig mulighed for at verificere, 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 i my.clerk.io under Developers > API Keys.

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

salt er blot en tilfældig streng brugt til saltning af hashfunktionen, mens hash er et SHA512-hash beregnet ud fra den Private API Key på følgende måde:

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

Et eksempel på en anmodning kunne være denne URL:

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

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