admesh-ui-sdk 1.0.50 → 1.1.0

package/INTEGRATION_GUIDE.md

@@ -2,6 +2,33 @@
 
 Complete guide for integrating AdMesh UI components into your application.
 
+## Visitor country
+
+Browser and extension calls send `X-AdMesh-Transport: browser`. AdMesh detects
+the visitor's country at the API from a recognized Cloudflare proxy or a bounded
+public-IP lookup. A saved `location.countryCode` is only a hint; fresh browser
+detection takes precedence. Missing or invalid country never defaults to US,
+and language/locale does not determine country.
+
+Server execution sends `X-AdMesh-Transport: server`. Supply the visitor country
+your backend detected when receiving the browser request as
+`location: { countryCode: 'IN' }`. The Node and Python Weave SDKs use their `geo` option for
+this value. AdMesh does not geolocate your server as though it were the visitor.
+These values are recorded as `platform_reported`, not independently verified.
+Flutter calls identify browser or native-device transport automatically.
+
+Country remains unknown when detection fails or a proxy chain cannot be
+recognized. Unknown visitors are excluded from country-restricted Brand Agents;
+explicit Global targeting remains eligible. IP location estimates the network's
+country and can reflect a VPN or corporate gateway rather than physical location.
+
+The API records `country`, `country_source`, and `country_resolution` in query,
+auction, and recommendation records. SDK upgrades must be released together
+with the backend country resolver. Do not configure ASGI to blindly trust
+forwarded headers from arbitrary public clients. The resolver recognizes direct
+Cloudflare connections and Cloud Run ingress whose last forwarded hop is
+Cloudflare; other proxy chains require verification before enabling detection.
+
 ## 🚀 Getting Started
 
 ### Step 1: Install the Package

package/README.md

@@ -1667,7 +1667,15 @@ outside-click dismissal. Sponsored and regular suggestions use the same geometry
 sponsored suggestions retain a distinct color and an Ad label. Ad cards keep
 their existing design.
 
-To retain the sponsored suggestion and additionally render its existing Tail creative
-card below the input container, add `data-sponsored-creative-placement="below-input-container"`.
-React integrations can set `sponsoredCreativePlacement="below-input-container"`. The
-default is `none`.
+By default, always-visible suggestions accompany the page-view sponsored creative
+below the input container. The default script settings are:
+
+```html
+data-suggestion-trigger="always"
+data-suggestion-placement="below"
+data-sponsored-creative-placement="below-input-container"
+```
+
+The creative appears when the initial page-view auction returns a matching ad.
+Use `data-sponsored-creative-placement="none"` for suggestions only. React
+integrations use `sponsoredCreativePlacement="none"` to disable the card.