From ee3298e5e30b2cd4d5a65231fd0c7c48ba68656a Mon Sep 17 00:00:00 2001
From: gwendalaubert <gwendal.aubert@akeneo.com>
Date: Fri, 10 Jul 2026 10:43:04 +0200
Subject: [PATCH] docs(advanced-extensions): document PIM context postMessage
 for custom components

Custom Components had no documented way to track the locale/channel
currently selected on the product edit form, unlike iframe extensions
where this was already covered. DXIM-694 aligned the postMessage
mechanism between iframe and Custom Component extensions so both now
receive a context message on load and on locale/channel change, and
both support requesting it on demand via 'request_context'.

Add a 'PIM context changes' section to sdk-in-depth.md mirroring the
existing iframe.md documentation, and note in iframe.md that the
context message is also sent once on initial iframe load.
---
 content/advanced-extensions/sdk-in-depth.md | 47 +++++++++++++++++++++
 content/extensions/iframe.md                |  2 +-
 2 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/content/advanced-extensions/sdk-in-depth.md b/content/advanced-extensions/sdk-in-depth.md
index c59380ee1..8c64b972f 100644
--- a/content/advanced-extensions/sdk-in-depth.md
+++ b/content/advanced-extensions/sdk-in-depth.md
@@ -194,6 +194,53 @@ if ('product' in PIM.context) {
 }
 ```
 
+## PIM context changes
+
+`PIM.context` and `PIM.user` are a snapshot taken when your component loads. To keep track of the **locale** or **channel** currently selected by the user, listen for [PostMessage](https://developer.mozilla.org/docs/Web/API/Window/postMessage) events — the same mechanism used by iframe extensions.
+
+The PIM sends this message when your component loads, and again whenever the user changes locale or channel:
+
+```json
+{
+  "context": {
+    "locale": "en_US",
+    "channel": "ecommerce"
+  },
+  "user": {
+    "uuid": "c71228d3-695c-4ded-8f3d-b3ed881a1f59",
+    "username": "admin",
+    "groups": [
+      {"id": 8, "name": "IT support"},
+      {"id": 11, "name": "All"}
+    ]
+  }
+}
+```
+
+Listen for it with:
+
+```js
+window.addEventListener('message', event => {
+  if (event.data?.context) {
+    const {locale, channel} = event.data.context;
+    // React to the new locale/channel
+  }
+});
+```
+
+### Requesting context on demand
+
+In modern JavaScript frameworks like React, components may initialize after the initial context message was already sent, causing them to miss it. In that case, request it explicitly:
+
+```js
+window.parent.postMessage(
+  {
+    type: 'request_context'
+  },
+  '*'
+);
+```
+
 ## Navigation within the PIM
 
 The SDK  navigation method that allows you to open new tabs. This is useful for directing users to different sections of the PIM from your extension:
diff --git a/content/extensions/iframe.md b/content/extensions/iframe.md
index 643970e01..f8783e5c9 100644
--- a/content/extensions/iframe.md
+++ b/content/extensions/iframe.md
@@ -94,7 +94,7 @@ Example :
 
 ### Product, product model and reference entity record context change
 
-When the user changes the **PIM context** (such as selecting a different **locale** or **channel**), these changes are automatically propagated to the iframe via PostMessage.
+When the user changes the **PIM context** (such as selecting a different **locale** or **channel**), these changes are automatically propagated to the iframe via PostMessage. This same message is also sent once when the iframe first loads.
 
 The message contains :
 - A `context` object containing the selected `locale` and `channel`.