admesh-ui-sdk 1.0.51 → 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