From 2a723159448c41e5eb031eaf03c7d62fd4880073 Mon Sep 17 00:00:00 2001 From: Cid Lopes Date: Thu, 27 Feb 2025 14:30:28 +0200 Subject: [PATCH 1/6] Custom implementation tagging providers --- ...tagging-providers-custom-implementation.md | 304 ++++++++++++++++++ 1 file changed, 304 insertions(+) create mode 100644 guides/tagging-providers-custom-implementation.md diff --git a/guides/tagging-providers-custom-implementation.md b/guides/tagging-providers-custom-implementation.md new file mode 100644 index 0000000..754efa8 --- /dev/null +++ b/guides/tagging-providers-custom-implementation.md @@ -0,0 +1,304 @@ +# Nosto Tagging Providers Integration Guide + +This documentation explains how to implement Nosto tagging on headless frontends, PWA implementations, or custom themes that are neither Luma nor Hyva. + +## Table of Contents + +- [Introduction](#introduction) +- [Architecture Overview](#architecture-overview) +- [Data Structure](#data-structure) +- [Integration Methods](#integration-methods) + - [Method 1: REST API](#method-1-rest-api) + - [Method 2: GraphQL](#method-2-graphql) + - [Method 3: Direct JavaScript Implementation](#method-3-direct-javascript-implementation) +- [Implementing Tagging Providers](#implementing-tagging-providers) +- [Testing Your Implementation](#testing-your-implementation) +- [Troubleshooting](#troubleshooting) + +## Introduction + +Nosto's tagging providers are a flexible way to send data to Nosto without requiring the traditional DOM-based tagging approach. This method is particularly useful for headless implementations, PWAs, or any frontend that doesn't follow Magento's traditional rendering approach. + +## Architecture Overview + +The tagging provider system consists of three main components: + +1. **Data Generation**: Magento backend prepares structured data for Nosto +2. **Data Delivery**: Methods to deliver this data to the frontend +3. **Provider Registration**: JavaScript that registers the data with Nosto + +## Data Structure + +The tagging provider data follows this basic structure: + +```javascript +{ + "pageType": "product", // product, category, frontpage, cart, search, notfound, order + "products": [...], // array of product objects when on product page + "cart": {...}, // cart data + "customer": {...}, // customer data + "categories": [...], // array of category paths + "variation": "...", // pricing variation or currency information + "searchTerm": "..." // on search pages +} +``` + +## Integration Methods + +### Method 1: REST API + +You can create a custom endpoint to retrieve the tagging data: + +1. **Create an API endpoint** in your Magento module: + +```php +taggingProvider = $taggingProvider; + $this->request = $request; + } + + public function getTaggingData($pageType) + { + // Set page type from API parameter + $this->taggingProvider->setData('page_type', $pageType); + + // Return the tagging configuration + return $this->taggingProvider->getTaggingConfig(); + } +} +``` + +3. **Register in di.xml**: + +```xml + +``` + +4. **Define in webapi.xml**: + +```xml + + + + + + +``` + +### Method 2: GraphQL + +For PWA implementations, GraphQL is often preferred: + +1. **Create schema.graphqls**: + +```graphql +type Query { + nostoTaggingData( + pageType: String! + ): NostoTaggingData @resolver(class: "Vendor\\Module\\Model\\Resolver\\NostoTaggingResolver") +} + +type NostoTaggingData { + pageType: String + products: [NostoProduct] + cart: NostoCart + customer: NostoCustomer + categories: [String] + variation: String + searchTerm: String +} + +# Define other required types (NostoProduct, NostoCart, etc.) +``` + +2. **Create the resolver**: + +```php +taggingProvider = $taggingProvider; + } + + public function resolve( + Field $field, + $context, + ResolveInfo $info, + array $value = null, + array $args = null + ) { + $pageType = $args['pageType'] ?? 'unknown'; + $this->taggingProvider->setData('page_type', $pageType); + + return $this->taggingProvider->getTaggingConfig(); + } +} +``` + +### Method 3: Direct JavaScript Implementation + +If you're building a non-Magento frontend but using Magento's backend, you can include the Nosto tagging-providers.js script directly: + +```html + + + +``` + +## Implementing Tagging Providers + +In your frontend application, after retrieving the data, you need to register the tagging providers: + +```javascript +function initTagging(taggingConfig) { + // Wait for nostojs to be available + function waitForNostoJs(callback, maxAttempts = 50, interval = 100) { + if (typeof nostojs === 'function') { + callback(); + return; + } + + let attempts = 0; + const checkNostoJs = setInterval(function() { + attempts++; + + if (typeof nostojs === 'function') { + clearInterval(checkNostoJs); + callback(); + return; + } + + if (attempts >= maxAttempts) { + clearInterval(checkNostoJs); + console.log('Failed to load nostojs after ' + maxAttempts + ' attempts'); + } + }, interval); + } + + // Register the tagging providers + function setupTaggingProviders() { + nostojs(function (api) { + // Register the page type + api.internal.setTaggingProvider("pageType", function () { + return taggingConfig.pageType; + }); + + // Register products if available + if (taggingConfig.products) { + api.internal.setTaggingProvider("products", function () { + return taggingConfig.products; + }); + } + + // Register cart if available + if (taggingConfig.cart) { + api.internal.setTaggingProvider("cart", function () { + return taggingConfig.cart; + }); + } + + // Register customer if available + if (taggingConfig.customer) { + api.internal.setTaggingProvider("customer", function () { + return taggingConfig.customer; + }); + } + + // Register categories if available + if (taggingConfig.categories) { + api.internal.setTaggingProvider("categories", function () { + return taggingConfig.categories; + }); + } + + // Register variation if available + if (taggingConfig.variation) { + api.internal.setTaggingProvider("variation", function () { + return taggingConfig.variation; + }); + } + + // Register search term if available + if (taggingConfig.searchTerm) { + api.internal.setTaggingProvider("searchTerm", function () { + return taggingConfig.searchTerm; + }); + } + }); + } + + waitForNostoJs(setupTaggingProviders); +} +``` + +## Testing Your Implementation + +1. **Verify data structure**: Ensure your API returns properly formatted data +2. **Check Nosto Debug Toolbar**: Enable the Nosto Debug Toolbar to verify data is being sent +3. **Validate with Nosto Dashboard**: Check if data appears in the Nosto dashboard +4. **Test recommendations**: Ensure recommendations appear on your pages + +## Troubleshooting + +Common issues and solutions: + +| Issue | Solution | +|-------|----------| +| Nosto script not loading | Make sure the Nosto script is included before tagging providers | +| Data not appearing | Check browser console for errors, verify data structure | +| Recommendations not personalizing | Ensure customer data is correctly formatted | +| Multiple currencies not working | Check variation ID is properly passed | + +For more detailed assistance, consult the Nosto Support team or refer to the [official Nosto documentation](https://docs.nosto.com/). From 40c936bbaa48a60ccc3265e1dec9ca04a970d49c Mon Sep 17 00:00:00 2001 From: Cid Lopes Date: Thu, 27 Feb 2025 14:33:17 +0200 Subject: [PATCH 2/6] Update spellchecker --- .github/config/.wordlist.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/config/.wordlist.txt b/.github/config/.wordlist.txt index c31b2f0..af95f9b 100644 --- a/.github/config/.wordlist.txt +++ b/.github/config/.wordlist.txt @@ -179,4 +179,7 @@ randomstring SSL experienceleague Hyvä +Hyva +Luma +graphqls PWAs \ No newline at end of file From 1aad7247fd688bdce6d9bfb7b91b05dbf5300926 Mon Sep 17 00:00:00 2001 From: Artiom Matvejev Date: Thu, 20 Mar 2025 15:15:25 +0200 Subject: [PATCH 3/6] Add link --- guides/tagging-providers-custom-implementation.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/guides/tagging-providers-custom-implementation.md b/guides/tagging-providers-custom-implementation.md index 754efa8..b2c5b21 100644 --- a/guides/tagging-providers-custom-implementation.md +++ b/guides/tagging-providers-custom-implementation.md @@ -29,8 +29,10 @@ The tagging provider system consists of three main components: ## Data Structure -The tagging provider data follows this basic structure: +For more details, refer to the Nosto API documentation: +https://nosto.github.io/nosto-js/interfaces/client.TaggingData.html +The tagging provider data follows this basic structure: ```javascript { "pageType": "product", // product, category, frontpage, cart, search, notfound, order From 669dd097e236c8530f85fe41b0b5925238204cbc Mon Sep 17 00:00:00 2001 From: Artiom Matvejev Date: Thu, 20 Mar 2025 15:21:06 +0200 Subject: [PATCH 4/6] Test --- .github/config/.wordlist.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/config/.wordlist.txt b/.github/config/.wordlist.txt index af95f9b..4cd6bdf 100644 --- a/.github/config/.wordlist.txt +++ b/.github/config/.wordlist.txt @@ -182,4 +182,6 @@ Hyvä Hyva Luma graphqls -PWAs \ No newline at end of file +PWAs +webapi +htmlcontent \ No newline at end of file From d934cbe8155116842c3bb6d716740a337772ec5f Mon Sep 17 00:00:00 2001 From: Artiom Matvejev Date: Thu, 20 Mar 2025 15:22:42 +0200 Subject: [PATCH 5/6] Update spell --- .github/config/.wordlist.txt | 3 +-- .github/config/spellcheck.yml | 1 + 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/config/.wordlist.txt b/.github/config/.wordlist.txt index 4cd6bdf..8ac7e0c 100644 --- a/.github/config/.wordlist.txt +++ b/.github/config/.wordlist.txt @@ -183,5 +183,4 @@ Hyva Luma graphqls PWAs -webapi -htmlcontent \ No newline at end of file +webapi \ No newline at end of file diff --git a/.github/config/spellcheck.yml b/.github/config/spellcheck.yml index c726627..4c93205 100644 --- a/.github/config/spellcheck.yml +++ b/.github/config/spellcheck.yml @@ -19,6 +19,7 @@ matrix: - code - pre - a + - htmlcontent sources: - '**/*.md' default_encoding: utf-8 \ No newline at end of file From 2fa1674f1bef3fa945960aa890ebaaf9914a30ac Mon Sep 17 00:00:00 2001 From: Artiom Matvejev Date: Fri, 28 Mar 2025 09:29:06 +0200 Subject: [PATCH 6/6] Whitelist word --- .github/config/.wordlist.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/config/.wordlist.txt b/.github/config/.wordlist.txt index 8ac7e0c..75f81cd 100644 --- a/.github/config/.wordlist.txt +++ b/.github/config/.wordlist.txt @@ -183,4 +183,5 @@ Hyva Luma graphqls PWAs -webapi \ No newline at end of file +webapi +TaggingData \ No newline at end of file