A fast and simple JavaScript library specifically targeted at collecting search and search related browser events.
\n\n
\n \n \n \n \n \n \n \n \n
\n\n# Description\n\n`search-collector` is a tiny JavaScript library for tracking search related events on e-commerce websites. It's built\nwith TypeScript and combines OOP (Object Oriented\nProgramming) and a sprinkle of FP (Functional Programming). In it's core it is meant to gather tracking data from\nthe DOM elements as soon as the page\nhas loaded.\n\n# Getting started\n\nCheckout the Demo\nand Blueprint\nor `npm i -S search-collector`\n\n# Concepts\n\nThe library is built around three main concepts:\n\n## Resolver\n\nA resolver is a function which will return a specific value.\n\n```typescript\nconst sessionNameResolver = (someArg) => {\n\treturn \"my-session-\" + someArg;\n};\n```\n\n## Collector\n\nA collector is a class which is responsible for gathering tracking data. All collectors have to extend\nthe `AbstractCollector` class which ships with some basic functionality and fields.\n\n```typescript\nimport {AbstractCollector} from \"search-collector\";\n\nexport class BrowserCollector extends AbstractCollector {\n\tprivate readonly sessionResolver: StringResolver;\n\n\tconstructor(sessionResolver) {\n\t\tsuper(\"browser\");\n\t\tthis.sessionResolver = sessionResolver;\n\t}\n\n\tattach(writer: Writer, log: Logger) {\n\t\twriter.write({\n\t\t\ttype: this.getType(),\n\t\t\tsid: this.resolve(this.sessionResolver, log, \"someResolverArg\"),\n\t\t\tagent: this.getWindow().navigator.userAgent\n\t\t});\n\t}\n}\n```\n\n## Writer\n\nA writer is responsible to deliver the data gathered by collectors to your tracking destination.\n\n```typescript\n//typescript\nclass MyWriter implements Writer {\n\twrite(data: any) {\n\t\tfetch(\"/my-endponit\", {\n\t\t\tmethod: \"POST\",\n\t\t\tbody: JSON.stringify(data)\n\t\t});\n\t}\n}\n```\n\n# Logging\n\n`search-collector` ships with a default set of `Logger` and `LoggerTransport`. In most cases you just want to use or add\na new `LoggerTransport`. By default `TransportLogger` is used which will direct all log messages to all\nprovided `LoggerTransports`.\n\nA `LoggerTransport` directs all implemented log levels to an output e.g. browser console or an REST endpoint. If you add\nmultiple transports all of them are invoked.\n\n## Example configuration\n\nLog to the console if `debug` is enabled or send error logs to an SQS queue if `debug` is disabled:\n\n```javascript\nif (debug) {\n\t// log all messages to the browser console\n\tcollector.addLogTransport(new ConsoleTransport());\n} else {\n\t// send all error log messages to an SQS queue\n\tcollector.addLogTransport(new SQSErrorTransport(\"https://your-sqs-queue.com/queue\"));\n}\n```\n\n## Implement LoggerTransport\n\nIf you need more than SQS or console transport you can implement your own by implementing the desired log level:\n\n```typescript\n//typescript\nclass MyLoggerTransport extends LoggerTransport {\n\terror(msg: string, ...dataArgs) {\n\t\tfetch(\"/my-endpoint\", {\n\t\t\tmethod: \"POST\",\n\t\t\tbody: JSONT.stringify({args: dataArgs})\n\t\t});\n\t}\n}\n\ncollector.addLogTransport(new MyLoggerTransport());\n```\n\n## Override Logger\n\nYou could also implement your own Logger. Instead of just implementing the log level you want to handle like in\nthe `LoggerTransport` you have to implement all log levels when you override the entire `Logger`.\n\n**Please be aware of that no LoggerTransports are called if you override the Logger**\n\n# Available components\n\n## Collectors\n\nSee also\n\n#### AbstractCollector\n\nA utility base class for collectors\n\n#### AssociatedProductCollector\n\nCollect information if an associated product (recommended, people also bought) was clicked\n\n#### BasketClickCollector\n\nCollect id and price if an item was add into the basket\n\n#### BrowserCollector\n\nCollect basic browser information. Note that depending on how you use this you may need to consult the GDPR guidelines\n\n#### CheckoutClickCollector\n\nCollect product information about bought products\n\n#### ClickCollector\n\nA base class which attached as click listener to all elements matching the supplied css expression\n\n### ClickWriterResolverCollector\n\nA base class which will pass the writer, type and logger to the resolver for greater flexibility\n\n#### FilterClickCollector\n\nCollect information about click events on search filters\n\n#### FiredSearchCollector\n\nCollect information that search was fired. Meant to be used on the product listing page.\n\n#### GenericEventCollector\n\nCollect different type of events via a custom event. The custom event should hold the properties \"type\" and \"data\" in\nthe custom payload.\n\n#### ImpressionCollector\n\nCollect information upon product display in the browser viewport\n\n#### ProductClickCollector\n\nCollect information about clicks on products inside the search result\n\n#### InstantSearchQueryCollector\n\nCollect search events from a search-as-you-type type of setup\n\n#### RedirectCollector\n\nRecognizes if the customer got redirect during the search process and tracks an appropriate event for it\n\n#### SearchResultCollector\n\nCollect information upon search\n\n#### SuggestSearchCollector\n\nTracks if a search was triggered by an as you type suggestion\n\n#### WriterResolverCollector\n\nA base class which resolves immediately and passing the writer, the type of the event + context to the provided resolver\nfunction.\n\n## Resolver\n\nSee also\n\n#### cookieResolver\n\nResolves to the string value of a cookie or empty string if no cookie with that name exists\n\n#### cookieSessionResolver\n\nCreate a session id which will last for 30 min or retrieves the session id if one already exists using cookies\n\n#### positionResolver\n\nResolves the position of an element relative to all elements matching the provided css selector\n\n#### debugResolver\n\nResolves to boolean value based on the presence and value of a query parameter called \"debug\" (?debug=true). The result\nis persisted in localStorage across page reloads until you invoke the page with ?debug=false which will make this\nresolver return false until you toggle it on again\n\n#### Query\n\nUtility class for string representation of search and filter queries\n\n#### Trail\n\nPersists a search phrase trail (Query, timestamp, type) in localStorage for each invocation of the register function.\nYou can then check for the presence of a trail with fetch(id) to relate e.g. event on product detail page to a search\nquery. All our Collectors are using this class already if appropriate and automatically append to the request using the\nTrailWriter\n\n## Writer\n\nSee also\n\n#### Base64EncodeWriter\n\nPack the data by first URL encoding it to make sure all special chars are correctly represented and then apply URL-safe\nbase64 encoding.\n\n#### BrowserTrackingWriter\n\nAppends browser related tracking data to the event like referer or browsers language\n\n#### BufferingWriter\n\nBuffer incoming events for 1s and then write them out in bulk. Keeps the information across pages making sure no data is\nlost.\n\n#### DebugWriter\n\nLogs the data to the browsers console if the debug flag is true\n\n#### DefaultWriter\n\nA utility class which combines the following writers in order:\n\n- SQSEventWriter or RestEventWriter\n- BufferingWriter\n- Base64EncodeWriter\n- DebugWriter\n- QueryWriter\n- TrailWriter\n- JSONEnvelopeWriter\n- BrowserTrackingWriter\n\n#### JSONEnvelopeWriter\n\nWraps the event in a JSON envelope, enrich each record with timestamp, session and channel information.\n\n#### QueryWriter\n\nAppends the Query class string representation to the event using the provided queryResolver\n\n#### RestEventWriter\n\nWrite events to a REST endpoint\n\n#### SplitStreamWriter\n\nCalls all writers passed to the constructor error safe\n\n#### SQSEventWriter\n\nWrite events to an SQS queue\n\n#### TrailWriter\n\nAppends the trail data to the event\n","readmeFilename":"README.md"}
![\"Searchhub](\"https://avatars.githubusercontent.com/u/29304684?v=4\")
\n![\"build](\"https://github.com/searchhub/search-collector/actions/workflows/build.yml/badge.svg\"){kind=icon}
\n ![\"test](\"https://github.com/searchhub/search-collector/actions/workflows/tests.yml/badge.svg\"){kind=icon}
\n ![\"license\"](\"https://img.shields.io/npm/l/search-collector\")
![\"downloads\"](\"https://img.shields.io/npm/dw/search-collector\")
![\"dependencies\"](\"https://img.shields.io/librariesio/release/npm/search-collector\")
![\"version\"](\"https://img.shields.io/npm/v/search-collector\")
![\"stars\"](\"https://img.shields.io/github/stars/searchhub/search-collector?style=social\")
![\"twitter\"](\"https://img.shields.io/twitter/follow/cxpsearchhub?style=social\")