Data Feeds

Oversigt #

Uanset din eCommerce-platform, 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 variationer 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 tilgængelige til 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 opbevares i databasen.

Vi anbefaler at generere JSON feed(s) mindst én gang om dagen, men ideelt set oftere. De kan også genereres på anmodning, 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.

Null-værdier #

Ucheckede null-værdier er en sikker måde for fejl at snige sig ind over tid. Hvis en attribut ikke eksisterer for et givet produkt, kategori eller ordre, skal du blot udelade attributten.

ID-værdi typer #

Vi anbefaler stærkt at bruge heltal som ID’er, men det er også muligt at bruge strenge. Du skal altid forpligte dig til 1 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 understregninger.
Dermed kunne et gyldigt attributnavn være brand_name, men ikke läbel-mærke

At bruge bindestreger eller specialtegn i attributnavne vil få dem til at blive ignoreret i synkroniseringen.

Objektstruktur #

JSON feeds består af en liste af objekter, med en række felter, der udgør deres data.

Objekter skal som minimum indeholde de nødvendige felter for typen, så Clerk.io’s AI kan fungere korrekt, og valgfrit kan de indeholde eventuelle ekstra attributter tilgængelige i eCommerce-platformen.

Produkter #

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

Nedenfor kan du se de nødvendige felter og eksempler på valgfrie, der ofte bruges af eCommerce-butikker.

Eksempel JSON #

[
  {
    "id": 135,
    "name": "Lightsaber",
    "description": "Antique Rebel Lightsaber",
    "price": 99995.95,
    "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_names": ["Green","Red"],
    "color_codes": ["#7CFC00","#FF3131"],
    "reviews_amount": 164,
    "reviews_avg": 4.8
  },
  {
    "id": 261,
    "name": "Death Star Deluxe",
    "description": "Death Star - Guaranteed idiot proof",
    "price": 99999999999999.95,
    "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 vil du måske holde 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 aldrig kommer tilbage, er det en god idé at holde historien om disse produkter intakt, så Clerk kan bruge det til at forbedre resultaterne.

For at gøre dette, tilføj den specielle attribut index: false til produktobjekterne, der skal holdes uden at blive indekseret. Clerk vil derefter bruge historikken for deres salg til at vise resultater, men de vil aldrig blive vist i nogen API-opkald.

For andre produkter skal du simpelthen 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 gives for hver kategori.

Nedenfor kan du se de nødvendige felter og 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 er logget og slettes ikke, når de fjernes fra feedet. De skal 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 i øjeblikket kun synkroniseres via CRUD API. Tjek dokumentationen her.

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

Nedenfor kan du se de nødvendige 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. De angivne attributter bliver derefter slået sammen med kundens email eller kunde ID fra ordrer for at skabe en enkelt kundeprofil til brug med Audience segmentering.

Nedenfor kan du se de nødvendige felter og 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 er generelt alle typer eCommerce-indhold, der ikke klassificeres som et produkt eller en kategori. Det kunne være artikler, blogindlæg, landingssider, mærkesider og andre typer skriftligt indhold.

Nedenfor kan du se de nødvendige felter og 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": "Åbningstider",
    "text": "Den primære tekst om vores åbningstider..."
 },
  {
    "id": 1354,
    "type": "blog",
    "url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
    "title": "Nyt Blogindlæg",
    "text": "Den primære tekst om vores åbningstider...",
    "keywords": ["blog", "indlæg", "nyt"]
 }
]

Flersprog #

Clerk.io fungerer bedst, når du opretter separate Butikker for hvert sprog. Hver butik kan konfigureres med sproget for indholdet, hvilket gør, at søgningen forstår grammatik og stavefejl meget bedre.

Desuden har kunder fra forskellige regioner eller lande tendens til at have forskellige præferencer og søgemønstre, hvilket betyder, at det fungerer bedst at adskille ordredataene i forskellige butikker også.

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

Alle tekstattributter skal have sprogkoder, selvom indholdet indeni dem er det samme, for at sikre, at de er søgbare for sproget.

Når du laver API-opkald, skal du inkludere parameteren language og den matchende sprogkode 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_names": ["Green","Red"],
    "color_codes": ["#7CFC00","#FF3131"],
    "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
 }
]

Eksempelopkald #

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 sit nøjagtige navn. Hvis dit sprog ikke er på nedenstående liste, skal du vælge et sprog, der bruger samme rod, eller simpelthen “english”. Det vil stadig fungere, men grammatikneutralisering i søgningen vil være mindre effektiv.

• dansk
• hollandsk
• engelsk
• finsk
• fransk
• tysk
• italiensk
• norsk
• portugisisk
• russisk
• spansk
• svensk

Flere Feeds #

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

Med denne tilgang bygger du individuelle feedfiler for hver af dine objekter. Dette bruger synkroniseringsmetoden 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,
 },
  ...
]

Pagination #

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: Antallet af objekter, der skal returneres pr. side.
• offset: Indekset for det første objekt, der skal returneres på en side.

Clerk.io’s importer kan konfigureres til at sende disse parametre til dit feedkode. Du skal blot vælge det antal objekter, du vil hente pr. side.

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

{{limit}} vil indeholde det nummer, du konfigurerer i importerindstillingerne. {{offset}} vil starte ved 0 i det første opkald og fortsætte med at vokse baseret på limit.

F.eks.

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

Den stoppebetingelse 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, når de importeres, så du skal bruge CRUD API-opkald til at fjerne objekter fra Clerk.io’s database.

Multi-feed-løsningen understøtter den valgfri funktion at sende kun de data, der er ændret 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 er konfigureret til kun at returnere objekter, der er blevet ændret i et angivet antal dage, når anmodningen inkluderer forespørgselsparameteren modified_after.

Tilføj derefter et antal dage i feltet mærket Incremental time {{modified_after}} fundet i Clerk.io’s importerindstillinger.

Dette vil få Clerk.io’s importer 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 forespørgselsparameteren modified_after til dit feed og inkludere tagget, der indsætter det antal dage, du har konfigureret. 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-godkendelse, hvis det er muligt.

Derudover kan du fra importerindstillingerne aktivere Token Authentication. Clerk.io vil derefter inkludere en autorisation header på hver HTTP-anmodning, som du skal verificere, før du returnerer dataene:

X-Clerk-Authorization: Bearer THE_TOKEN

Du kan verificere tokenet med en POST-anmodning 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 #

Udover objekterne selv understøtter denne tilgang to yderligere parametre:

• created: Et unix-tidsstempel for, hvornår feedet sidst blev opdateret. Clerk.io’s importer bruger dette til at identificere, om nye data skal hentes.
• 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, for eksempel ved at fjerne dublerede produkter eller kategorier og konvertere strenge til heltal eller flydende tal.

Eksempel Feed #

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

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

Sikkerhed #

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

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

Derudover giver Clerk en ekstra sikkerhedslag ved at lade dig verificere, at feedanmodningen kommer fra en betroet kilde (dvs. os).

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

Alle Clerk.io-anmodninger via HTTP eller HTTPS inkluderer to forespørgselsparametre hash og salt.

salt er blot en tilfældig streng, der bruges til at salte hash-funktionen, mens hash er en SHA512-hash beregnet 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 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 gøre den samme beregning på din server og sammenligne hash værdierne for at bekræfte, at de er de samme, hvilket betyder, at anmodningen kommer fra Clerk.io