Allow unknown product keys for product details

[wuservices]

Adds additional item parameter mappings for GA4 ecommerce including category2-5, which fixes #3.

Parameters from: https://www.thyngster.com/ga4-measurement-protocol-cheatsheet/

[wuservices]

If we're able to send nested categories to GA4, but other tools only accept a single category, what do you think of allowing sending category1 to optionally override category here?

Use case:

You have a 3-level hierarchy: Parent/Child/Grandchild. This is the category you would send to most tools, which only accept a single level. However, if you had that, and also defined category2=Child, category3=Grandchild, now there's not really a way to say that category=Parent for GA4 (or other tools that handle nested categories). I propose we could also add a category1, so that you can set category1=Parent, which will be used instead of category if the tool supports multiple levels and if it's defined.

This isn't in the PR, currently as I wanted to see what you thought given this has potential implications for all ecommerce tools.

[bjesus]

hey @wuservices ! I'm concerned that this change is actually not about extending the GA4 component per se, but rather, it is extending the Ecommerce API. Allowing keys like category2 in the Ecommerce API would mean that we'd need to figure out how to support them with other tools too, and we generally trying to avoid changing the API just to accommodate one specific tool.

Nothing generally prevents you from adding custom keys to the payload when calling zaraz.ecommerce, so for example doing something like zaraz.ecommerce("Product Added", {category: "shirts", ca2: "polo"}) is perfectly doable. The issue is that currently Zaraz will see this as a custom field and will therefore prepend ep. to the key name, and I suspect it will then end in the wrong place. However, I believe that this can be fixed by setting a specific logic for these specific keys, specifically on ecommerce events. By doing that, users will be able to use ca2, ca3 etc when they're calling zaraz.ecommerce, but the Ecommerce API itself will change.

Does that make sense?

[wuservices]

Hi @bjesus thanks for taking a look. I agree this could be a bigger discussion if thinking about extending the Ecommerce API completely, especially because nested categories is a feature that most APIs will lack and it's also something that each provider is likely to have a slightly different model for.

However, I think the idea of adding custom keys is a general need here and would be a good strategy to handle in general. My understanding of the current code is that buildProductRequest only maps in the known keys and everything else is discarded. Is ep. only used for extra keys at the root vs in items?

One concern with adding custom keys for each item and blindly mapping them to each tool is that some tools may not like the extra keys (hypothetically at least). Would it be helpful to namespace additional custom keys and have a way to pass them in both at the root and for any products array?

zaraz.ecommerce('Product List Viewed', {
  products: [
    { 
      product_id: '999555321',
      sku: '2671033',
      name: 'V-neck T-shirt',
      brand: 'Cool Brand',
      variant: 'White',
      price: 14.99,
      currency: 'usd',
      value: 18.99, 
      position: 1,
      category: 'T-shirts',
      _ga4_ca2: 'polo',
    }
  ]
})

[bjesus]

Hey @wuservices, ep. and epn. are indeed only used for root extra keys. We will accept a PR that keeps unused products keys in the products array sent to GA4. will that solve your issue?

[wuservices]

@bjesus I think accepting unknown keys for product data would be pretty flexible. It also seems like it'd simplify the code a bit.

I updated the PR with what I think this would look like.

[wuservices]

@bjesus just checking in here. Do the updated changes look like what you had in mind? Happy to tweak if needed. Thanks!

[wuservices]

We will accept a PR that keeps unused products keys in the products array sent to GA4. will that solve your issue?

@bjesus @simonabadoiu how does the proposed change look?

The idea is that there is no longer an allowlist for PRODUCT_DETAILS so all will get sent. This would allow item attributes unsupported by Zaraz ecommerce to be sent, including any custom item level custom dimensions. I didn't have a great way to test this though.

[wuservices]

@bjesus does this look good? It seems like this will also allow users to add custom item-scoped custom parameters too.