Data Feeds

Oversigt #

Uanset hvilken eCommerce-platform du bruger, 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 til forskellige objekter
• En enkelt fil, der indeholder alle objekter

De to løsninger bruger den samme objektstruktur, men har forskellige funktioner til sikring og import, 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 feedet/feeds mindst én gang om dagen, men ideelt set oftere. De kan også genereres på anmodning, når Clerk.io’s importer anmoder om dem.

Feedet/feeds 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 #

Uden kontrol 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 kraftigt 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

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

Objekters Struktur #

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 at Clerk.io’s AI kan fungere korrekt, og valgfrit kan de indeholde eventuelle ekstra attributter, der er 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 farve, størrelse, materiale, osv.

Nedenfor kan du se de nødvendige felter og eksempler på valgfrie felter, 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 gerne beholde 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 bevares uden at blive indekseret. Clerk vil så bruge historikken for deres salg til at vise resultater, men de vil aldrig blive vist i nogen API-opkald.

For andre produkter skal 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 er givet for hver kategori.

Nedenfor kan du se de nødvendige felter og eksempler på valgfrie felter, 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’erne og e-mailadressen/kunde-ID’en inden for ordrer til at analysere kundeadfærd og identificere tendenser. Sammen med produkter 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 oprette en enkelt kundepost til brug med Audience segmentering.

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

Nedenfor kan du se de nødvendige felter og eksempler på valgfrie felter, 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"]
 }
]

Flersprogede #

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øgning 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 ordredata i forskellige butikker også.

Et alternativ til dette 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 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, vælg et sprog, der bruger den samme rod, eller blot “english”. Det vil stadig fungere, men grammatikneutralisering i søgning 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 den er effektiv for din server og tilbyder den højeste grad af kontrol,

Med denne tilgang opbygger 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.

Hver 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 ønsker at 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 kontinuerligt vokse baseret på limit.

F.eks.

• Opkald 1: limit=100&offset=0
• Opkald 2: limit=100&offset=100
• Opkald 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, når de importeres, så du skal bruge CRUD API-opkald for at fjerne objekter fra Clerk.io’s database.

Multi-feed-løsningen understøtter den valgfri funktion til 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 starte med at sikre, at dit feed er konfigureret til kun at returnere objekter, der er blevet ændret i en specificeret mængde dage, når anmodningen inkluderer forespørgselsparameteren modified_after.

Derefter tilføj 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, som 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