Data Feeds

Oversigt #

Uanset din eCommerce platform, 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 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 at sikre og importere dem, som beskrives 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 bliver bevaret i databasen.

Vi anbefaler at generere JSON feed(s) mindst én gang dagligt, men helst oftere. De kan også genereres efter behov, når Clerk.io’s importør 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 for fejl at snige sig ind over tid. Hvis en attribut ikke findes for et givent produkt, kategori eller ordre, bør attributten blot udelades.

ID-værdityper #

Vi anbefaler stærkt 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 kan 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

Hvis du bruger bindestreger eller specialtegn i attributnavnene, vil de blive ignoreret under synkronisering.

Objektsstruktur #

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

Objekter skal som minimum indeholde de pågældende felter for typen for, at Clerk.io’s AI fungerer korrekt. Derudover kan de indeholde ekstra attributter, der er tilgængelige i eCommerce-platformen.

Produkter #

Hvert objekt repræsenterer et enkelt produkt. Hvis du har konfigurerbare produkter, anbefaler vi kun at sende parent produktet og inkludere attributter, der beskriver child-produkterne, såsom color, size, material osv.

Nedenfor kan du se de påkrævede felter samt anbefalede, der ofte bruges af eCommerce-butikker.

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 kun er tilgængelige i en periode, kan det være en god idé at bevare historikken over disse produkter, så Clerk kan bruge det til at forbedre resultaterne.

For at gøre dette, tilføj attributten index: false til de produktobjekter, der skal bevares uden at blive indekseret. Clerk vil så bruge deres salgs-historik til visning, men de vil aldrig blive vist i nogen API-kald.

For andre produkter undlades attributten blot, eller sættes til index: true.

Kategorier #

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

Nedenfor ses de krævede felter samt eksempler på valgfrie, der ofte bruges af eCommerce-butikker.

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, når de fjernes fra feedet. De skal generelt kun sendes ved første import og kan derefter fjernes igen 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 tendenser. Sammen med products er det den vigtigste objekttype.

Nedenfor ses de påkrævede samt valgfrie felter. For at inkludere pakkedata, tilføj et tracking array til ordren. Send ikke pakker som et separat top-level objekt.

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,
    "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. Attributterne fusioneres derefter med kundens email eller customer ID fra ordrer for at skabe en samlet kundeprofil til brug med Audience segmentering.

Nedenfor ses de påkrævede felter samt eksempler på valgfrie, der ofte bruges af eCommerce-butikker.

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 eCommerce-indhold, der ikke klassificeres som et produkt eller en kategori. Det kan være artikler, blogindlæg, landingssider, brandsider og andre former for tekstindhold.

Nedenfor ses de påkrævede felter samt eksempler på valgfrie, der ofte bruges af eCommerce-butikker.

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

Flere sprog #

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

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

Et alternativ til dette er at opbygge flersprogede JSON-feeds, hvor alle tekstattributter præsenteres 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 frem på sproget.

Når du laver API-kald, så inkluder 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 ønskede sprog ikke er på listen nedenfor, så vælg et beslægtet sprog eller blot “english”. Det vil stadig fungere, men grammatisk 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 den er effektiv for din server og giver højest grad af kontrol.

Med denne tilgang bygger du individuelle feedfiler for hver objekttype. 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 dig mulighed for at paginere resultater ved at kode dit feed til at acceptere følgende forespørgselsparametre:

• limit: Antal 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 dit feed. Du skal blot vælge, hvor mange objekter du ønsker at hente per side.

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

{{limit}} vil indeholde det antal, du har konfigureret 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

Stopbetingelsen 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.

Løsningen med flere feeds understøtter den valgfrie funktion at sende kun de data, der er ændret inden for 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 er konfigureret til kun at returnere objekter, der er ændret inden for et angivet antal dage, når forespørgslen inkluderer query-parameteren modified_after.

Tilføj herefter et antal dage i feltet mærket Incremental time {{modified_after}} fundet 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 inkluderet i feeds.

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

Derudover kan du fra importørindstillingerne aktivere Token Authentication. Clerk.io vil så inkludere en autoriseringsheader 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 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 #

Med denne tilgang samler du alle dine objekter i én enkelt JSON-fil. Dette bruger sync-metoden kaldet Clerk.io JSON Feed.

Parametre #

Ud over 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 vurdere, om nye data bør indhentes.
• strict: Når true importeres alle data nøjagtigt som de er. Når false vil Clerk.io forsøge at rydde op i data, fx ved at fjerne dublerede produkter eller kategorier og omdanne teksttal til integers eller floats.

Eksempel-feed #

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

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

Sikkerhed #

Dine data er ekstremt forretningskritiske, så sikkerheden er altafgørende!

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 verificere, at feed-anmodningen er fra en betroet kilde (fx os).

Systemet er baseret på en delt hemmelighed; en privat 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, som 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 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 forespørgslen kan du udføre samme beregning på din server og sammenligne hash værdierne for at bekræfte, at de er identiske, hvilket betyder at anmodningen kommer fra Clerk.io