Klaviyo : Segmentation

the following guide will walk you through accessing klevu smart recommendation configurations and applying corresponding pre configured segments to web visitors via the klevu api to implement klaviyo segmentation logic with klevu smart recommendations, you need an active subscription to klaviyo and klevu smart recommendations (with personalization enabled) the intitial setup and configuration process takes place within the klevu merchant center detailed instructions on how to integrate klaviyo with klevu smart recommendations can be found here there are four key steps to consider 1\ fetch the applicable segments for the visitor 2\ apply the segments to the recommendations configuration 3\ request and display the klevu recommendations banner 4\ collect klevu analytics (impressions and interaction) 1\ fetch the applicable segments for the visitor three parameters are necessary to obtain the appropriate visitor segments 1\ klevu api key 2\ klevu session id 3\ klaviyo exchange id once the klevu session id and the klaviyo exchange id have been obtained, they can be stored locally and used in subsequent calls to klevu for recommendations { "name" "request session id ", "method" "post", "url" "https //visitor service ksearchnet com/public/1 0/\<klevu api key>/session", "description" "", "tab" "examples", "examples" { "languages" \[ { "id" "wmvxgdukthr5uu6qkxzm ", "language" "json", "code" "{\\"apikey\\" \\"\<klevu api key>\\"}\n", "customlabel" "request body" } ], "selectedlanguageid" "wmvxgdukthr5uu6qkxzm " }, "results" { "languages" \[ { "id" "k6b5 hveeene9ck5mpsam", "language" "200", "customlabel" "", "code" "{\n \\"apikey\\" \\"\<klevu api key>\\",\n \\"sessionid\\" \\"\<klevu session id>\\",\n \\"segmentinfo\\" {\n \\"segments\\" \[],\n \\"ttl\\" 3600\n }\n}" } ], "selectedlanguageid" "k6b5 hveeene9ck5mpsam" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[], "bodydataparameters" \[ { "name" "apikey", "kind" "required", "type" "string", "description" "the unique klevu apikey id of the store" } ], "formdataparameters" \[] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" } } retain the sessionid value for this user for use in subsequent api calls to klevu for a maximum of the ttl time at this point refresh the sessionid so as to retain continuity obtain klaviyo exchange id klaviyo holds identity and tracking information in a local browser cookie the exchange id is an encrypted identifier for a klaviyo profile id the value is commonly stored within the base64 encoded klaviyo cookie “ kla id” more information can be found on the klaviyo developer's website understanding cookies in klaviyo | klaviyo help center https //help klaviyo com/hc/en us/articles/360034666712 klaviyo developers https //developers klaviyo com/en/v1 2/reference/exchange retain the $exchange id value for this user for use in subsequent api calls to klevu obtain applicable visitor segments use the session endpoint to push the klaviyo exchangeid to klevu this will allow klevu to communicate with klaviyo directly and return the visitor's applied segmentation { "name" "request segments", "method" "post", "url" "https //visitor service ksearchnet com/public/1 0/\<klevu api key>/session", "description" "", "tab" "examples", "examples" { "languages" \[ { "id" "wsx4qj f mmv8ie6s0rba", "language" "json", "code" "{\n\t\\"apikey\\" \\"\<klevu api key>\\",\n\t\\"sessionid\\" \\"\<klevu session id>\\",\n\t\\"sessioninfo\\" {\n\t\t\\"connectorinfo\\" \[\n\t\t\t{\n\t\t\t\t\\"connectortype\\" \\"klaviyo\\",\n\t\t\t\t\\"exchangeid\\" \\"\<klaviyo exchange id>\\"\n\t\t\t}\n\t\t]\n\t}\n}", "customlabel" "request body" } ], "selectedlanguageid" "wsx4qj f mmv8ie6s0rba" }, "results" { "languages" \[ { "id" "mv91 vdmstn2yj9vbd2sy", "language" "200", "customlabel" "", "code" "{\n \\"apikey\\" \\"\<klevu api key>\\",\n \\"sessionid\\" \\"\<klevu session id>\\",\n \\"segmentinfo\\" {\n \\"segments\\" \[\n \\"\<segment id a>\\",\n \\"\<segment id b>\\",\n \\"\<segment id c>\\"\n ],\n \\"ttl\\" 173\n }\n}" } ], "selectedlanguageid" "mv91 vdmstn2yj9vbd2sy" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[], "bodydataparameters" \[ { "name" "apikey", "kind" "required", "type" "string", "description" "the unique klevu apikey id of the store" }, { "name" "sessionid", "kind" "required", "type" "string", "description" "the session id as obtained in the previous requests", "children" \[] }, { "name" "sessioninfo", "kind" "required", "type" "string", "description" "used to pass details of the session", "children" \[] }, { "name" "connectorinfo", "kind" "required", "type" "string", "description" "used to pass details of the applied connector", "children" \[] }, { "name" "connectortype", "kind" "required", "type" "string", "description" "the value should be \\"klaviyo\\" in this context", "children" \[] }, { "name" "exchangeid", "kind" "required", "type" "string", "description" "the vlaue of the klaviyo exchangeid as previously obtained", "children" \[] } ], "formdataparameters" \[] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" } } retain the segment value for this user for use in subsequent api calls to klevu important the segments may be updated for any given visitor throughout the session to keep the segments relevant, please request an updated segment list after the ttl has expired 2\ apply the segments to the recommendations configuration please review the section on api configurations docid\ gp pf1 nmovk01kou09nd for a complete list of applicable parameters to use based on the application/placement of the recommendation banner { "name" "use segments", "method" "get", "url" "https //config cdn ksearchnet com/recommendations/\<klevu api key>/settings/\<klevu recs key>", "description" "", "tab" "examples", "examples" { "languages" \[ { "id" "mscnayydtcns yxqiv dl", "language" "none", "code" "?sids=\<segment id a>,\<segment id b>,\<segment id c>\n", "customlabel" "query paramters" } ], "selectedlanguageid" "mscnayydtcns yxqiv dl" }, "results" { "languages" \[ { "id" "jq1mdftybzv46ikcvqwe2", "language" "200", "customlabel" "", "code" "{\n \\"metadata\\" {\n \\"title\\" \\"still looking for these?\\",\n \\"recskey\\" \\"\<klevu recs key>\\",\n \\"pagetype\\" \\"home\\",\n \\"logic\\" \\"recently viewed\\",\n \\"maxproducts\\" 10,\n \\"productthreshold\\" 1,\n \\"enabled\\" true,\n \\"spotkey\\" \\"\<klevu spot key>\\",\n \\"spotname\\" \\"home spot 1\\",\n \\"segmentkey\\" \<segment id a>,\n \\"segmentname\\" \\"just browsing\\"\n },\n \\"search\\" {\n \\"basepath\\" \\"\<klevu search domain> ksearchnet com/cs/v2/search\\",\n \\"payload\\" \\"{\\\\\\"recordqueries\\\\\\" \[{\\\\\\"id\\\\\\" \\\\\\"klevurecsitemlist\\\\\\",\\\\\\"typeofrequest\\\\\\" \\\\\\"search\\\\\\",\\\\\\"settings\\\\\\" {\\\\\\"typeofrecords\\\\\\" \[\\\\\\"klevu product\\\\\\"],\\\\\\"limit\\\\\\" 10}}]}\\"\n },\n \\"templates\\" {\n \\"base\\" \<klevu recs markup>\n },\n \\"styles\\" {\n \\"base\\" \<klevu recs css> \n },\n \\"scripts\\" {\n \\"recsobject\\" \<klevu recs scripts>\n }\n}" } ], "selectedlanguageid" "jq1mdftybzv46ikcvqwe2" }, "request" { "pathparameters" \[], "queryparameters" \[ { "name" "sids", "kind" "required", "type" "string", "description" "the segmentids returned as segmentinfo segments within the previous request\n\n\<segment id a>,\<segment id b>,\<segment id c>", "children" \[] } ], "headerparameters" \[], "bodydataparameters" \[], "formdataparameters" \[] }, "currentnewparameter" { "label" "query parameter", "value" "queryparameters" } } retain spotkey , spotname , segmentkey , segmentname for reference in the following analytics collection api calls to klevu the resulting search payload json object will be the query payload used to call klevu for the recommendations corresponding result set 3\ request and display the klevu recommendations banner use the provided query structure from the search payload json within the above response to retrieve the recommendations array from klevu see the klevu smart recommendations api overview for details on query specifics 4\ collect klevu analytics after the recommendations have been displayed, collect the analytics to send to klevu please use the appropriate event value for each event type product recommendation impression event = view recs list product clicks from recommendation banner event = select recs list { "name" "recommendation impression ", "method" "post", "url" "https //stats ksearchnet com/analytics/collect", "description" "", "tab" "examples", "examples" { "languages" \[ { "id" "7khvygkpzg3y ht ccqku", "language" "json", "code" "\[\n\t{\n\t\t\\"event\\" \\"view recs list\\",\n\t\t\\"event apikey\\" \\"\<klevu recs key>\\",\n\t\t\\"user profile\\" {\n\t\t\t\\"session id\\" \\"\<klevu session id>\\"\n\t\t},\n\t\t\\"event data\\" {\n\t\t\t\\"tags\\" \[\n\t\t\t\t\\"recspagetype\ home\\"\n\t\t\t],\n\t\t\t\\"list id\\" \\"\<klevu recs key>\\",\n\t\t\t\\"list name\\" \\"still looking for these?\\",\n\t\t\t\\"list logic\\" \\"recently viewed\\",\n\t\t\t\\"spot id\\" \\"\<klevu recs key>\\",\n\t\t\t\\"spot name\\" \\"home spot 1\\",\n\t\t\t\\"segment id\\" \<segment id a>,\n\t\t\t\\"segment name\\" \\"just browsing\\",\n\t\t\t\\"items\\" \[\n\t\t\t\t{\n\t\t\t\t\t\\"item id\\" \\"39814\\",\n\t\t\t\t\t\\"item name\\" \\"lorem ipsum\\",\n\t\t\t\t\t\\"price\\" \\"25 0\\",\n\t\t\t\t\t\\"currency\\" \\"usd\\",\n\t\t\t\t\t\\"item brand\\" \\"47\\",\n\t\t\t\t\t\\"item variant\\" \\"39814\\",\n\t\t\t\t\t\\"item group id\\" \\"67466\\",\n\t\t\t\t\t\\"index\\" 1,\n\t\t\t\t\t\\"quantity\\" 1\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\\"item id\\" \\"32697\\",\n\t\t\t\t\t\\"item name\\" \\"gypsum dolet\\",\n\t\t\t\t\t\\"price\\" \\"37 0\\",\n\t\t\t\t\t\\"currency\\" \\"usd\\",\n\t\t\t\t\t\\"item brand\\" \\"47\\",\n\t\t\t\t\t\\"item variant\\" \\"32697\\",\n\t\t\t\t\t\\"item group id\\" \\"83119\\",\n\t\t\t\t\t\\"index\\" 2,\n\t\t\t\t\t\\"quantity\\" 1\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\\"item id\\" \\"36888\\",\n\t\t\t\t\t\\"item name\\" \\"dolet ipsum\\",\n\t\t\t\t\t\\"price\\" \\"26 0\\",\n\t\t\t\t\t\\"currency\\" \\"usd\\",\n\t\t\t\t\t\\"item brand\\" \\"47\\",\n\t\t\t\t\t\\"item variant\\" \\"36888\\",\n\t\t\t\t\t\\"item group id\\" \\"69215\\",\n\t\t\t\t\t\\"index\\" 3,\n\t\t\t\t\t\\"quantity\\" 1\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t}\n]", "customlabel" "request body" } ], "selectedlanguageid" "7khvygkpzg3y ht ccqku" }, "results" { "languages" \[ { "id" "wbdkyam9kwr k256dr3i4", "language" "200", "customlabel" "", "code" "200 http response code" } ], "selectedlanguageid" "wbdkyam9kwr k256dr3i4" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[], "bodydataparameters" \[], "formdataparameters" \[] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" } } { "name" "recommendation product click ", "method" "post", "url" "https //stats ksearchnet com/analytics/collect", "description" "", "tab" "examples", "examples" { "languages" \[ { "id" "msv3rtwxyfzzvyttoubxr", "language" "json", "code" "\[\n\t{\n\t\t\\"event\\" \\"select recs list\\",\n\t\t\\"event apikey\\" \\"\<klevu recs key>\\",\n\t\t\\"user profile\\" {\n\t\t\t\\"session id\\" \\"\<klevu session id>\\"\n\t\t},\n\t\t\\"event data\\" {\n\t\t\t\\"tags\\" \[\n\t\t\t\t\\"recspagetype\ home\\"\n\t\t\t],\n\t\t\t\\"list id\\" \\"\<klevu recs key>\\",\n\t\t\t\\"list name\\" \\"still looking for these?\\",\n\t\t\t\\"list logic\\" \\"recently viewed\\",\n\t\t\t\\"spot id\\" \\"\<klevu recs key>\\",\n\t\t\t\\"spot name\\" \\"home spot 1\\",\n\t\t\t\\"segment id\\" \<segment id a>,\n\t\t\t\\"segment name\\" \\"just browsing\\",\n\t\t\t\\"items\\" \[\n\t\t\t\t{\n\t\t\t\t\t\\"item id\\" \\"39814\\",\n\t\t\t\t\t\\"item name\\" \\"lorem ipsum\\",\n\t\t\t\t\t\\"price\\" \\"25 0\\",\n\t\t\t\t\t\\"currency\\" \\"usd\\",\n\t\t\t\t\t\\"item brand\\" \\"47\\",\n\t\t\t\t\t\\"item variant\\" \\"39814\\",\n\t\t\t\t\t\\"item group id\\" \\"67466\\",\n\t\t\t\t\t\\"index\\" 1,\n\t\t\t\t\t\\"quantity\\" 1\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t}\n]", "customlabel" "request body" } ], "selectedlanguageid" "msv3rtwxyfzzvyttoubxr" }, "results" { "languages" \[ { "id" "2hhh3cihioyj7hojkbv7d", "language" "200", "customlabel" "", "code" "200 http response code" } ], "selectedlanguageid" "2hhh3cihioyj7hojkbv7d" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[], "bodydataparameters" \[], "formdataparameters" \[] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" } }