superwall · yusuftor · Sep 22, 2026 · Aug 16, 2026 · Aug 16, 2026 · Aug 16, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,131 @@
+name: 🐛 Bug report
+description: Report a bug in SuperwallKit. The more you give us up front, the faster we can find the cause.
+title: "[BUG] "
+labels: ["bug"]
+body:
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: New issue checklist
+      options:
+        - label: I have read the [documentation](https://superwall.com/docs) and this doesn't appear to be expected behavior
+          required: true
+        - label: I have searched [existing issues](https://github.com/superwall/Superwall-iOS/issues) and this is not a duplicate
+          required: true
+        - label: I have tried to reproduce the issue in a minimal sample project I can share
+          required: false
+  - type: input
+    id: affected-user
+    attributes:
+      label: Affected user
+      description: >
+        A link to a user who hit the bug lets us check their event logs, which is often the
+        fastest route to a diagnosis. In the
+        [dashboard](https://superwall.com/select-application?pathname=/applications/:app/users/v2),
+        open **Users**, search for the app user ID you pass to `Superwall.shared.identify(userId:)`
+        (or the `$SuperwallAlias:...` ID from `Superwall.shared.userId` if you don't identify users),
+        open the user, and paste the page URL. The link only opens for your own team and us,
+        but issues are public and the URL contains the user ID itself — so if your app user IDs
+        are personally identifying (e.g. an email address), paste the user's `$SuperwallAlias:...`
+        URL instead (shown on their user page), or share the link privately via the support chat
+        in the dashboard and mention this issue. If the bug isn't tied to a user (e.g. a build
+        error), write "N/A".
+      placeholder: https://superwall.com/applications/<appId>/users/v2/<userId>
+    validations:
+      required: true
+  - type: input
+    id: occurred-at
+    attributes:
+      label: When did it happen?
+      description: Approximate date and time the bug occurred, including timezone. Helps us correlate server-side logs.
+      placeholder: e.g. 2026-08-15 14:30 UTC
+  - type: input
+    id: sdk-version
+    attributes:
+      label: SuperwallKit version
+      placeholder: e.g. 4.16.3
+    validations:
+      required: true
+  - type: input
+    id: previous-sdk-version
+    attributes:
+      label: Last SDK version that worked
+      description: If the bug appeared after updating the SDK, which version were you on before?
+      placeholder: e.g. 4.15.4
+  - type: input
+    id: ios-version
+    attributes:
+      label: iOS version(s)
+      placeholder: e.g. iOS 26.5
+    validations:
+      required: true
+  - type: input
+    id: xcode-version
+    attributes:
+      label: Xcode version
+      placeholder: e.g. 26.1
+    validations:
+      required: true
+  - type: dropdown
+    id: installation
+    attributes:
+      label: Installation method
+      options:
+        - Swift Package Manager
+        - CocoaPods
+        - Other
+    validations:
+      required: true
+  - type: input
+    id: devices
+    attributes:
+      label: Devices/simulators affected
+      placeholder: e.g. iPhone 17 Pro, all simulators
+  - type: dropdown
+    id: repro-example
+    attributes:
+      label: Reproducible in the example app?
+      options:
+        - "Yes"
+        - "No"
+        - Haven't tried
+    validations:
+      required: true
+  - type: textarea
+    id: sdk-setup
+    attributes:
+      label: How is the SDK set up?
+      description: |
+        Briefly describe your integration — it changes which code paths run:
+        - Are you using a `PurchaseController` (e.g. with RevenueCat)? If so, where do you set `Superwall.shared.subscriptionStatus`?
+        - How do you present paywalls (`register(placement:)`, `PaywallView`, `getPaywall`)?
+        - Do you call `Superwall.shared.identify(userId:)`?
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the bug
+      description: A clear and concise description of the bug, including expected vs. actual behavior. Screenshots and screen recordings help a lot.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. ...
+        2. ...
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Debug logs
+      description: Set `options.logging.level = .debug` in `SuperwallOptions` before configuring the SDK, reproduce the bug, and paste the console output covering when it happened. Automatically formatted as code. Please redact anything personal — logs can contain user attributes you've set.
+      render: shell
+  - type: textarea
+    id: other
+    attributes:
+      label: Other information
+      description: Stack traces, crash reports, related issues, links, or anything else that gives context.
diff --git a/.swiftlint.yml b/.swiftlint.yml
@@ -3,6 +3,9 @@ excluded:
   - ${PWD}/Pods
   - ${PWD}/DerivedData
   - ${PWD}/.build
+  # Git worktrees live here, each holding a full copy of the SDK source, so
+  # linting them reports another branch's violations against this one.
+  - ${PWD}/.claude
   - ${PWD}/Examples
   - ${PWD}/Tests
   - ${PWD}/Sources/SuperwallKit/StoreKit/Products/Receipt Manager/ASN1Swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,27 @@
 
 The changelog for `SuperwallKit`. Also see the [releases](https://github.com/superwall/Superwall-iOS/releases) on GitHub.
 
+## 4.17.0
+### Enhancements
+
+- Adds `grantedEntitlements` so you can grant entitlements from your own backend, which the SDK merges with device and web entitlements.
+- Adds `userAttributes` to the `RedemptionInfo` you get from `didRedeemLink`, so you can read the answers someone gave on your web paywall funnel after they redeem in your app.
+- Adds `SuperwallOptions.devServer` for development builds: with a `superwall dev` server running, paywalls render from your live, local paywall code while configuration, placements, audience evaluation and assignment stay real. Use `.default` on a simulator, which finds the dev server on localhost automatically; on a physical device use `.url(...)` with the Device URL `superwall dev` prints. The dev server also activates test mode, disables preloading, and skips the test mode intro sheet.
+
+### Fixes
+
+- Fixes trial reminders being scheduled for users who bought without getting the intro offer.
+- Refreshes the IDFV, IDFA and tracking consent for integrations when the app becomes active or integration attributes are set again, and clears the IDFA when consent is revoked. These now also go into the user attributes `idfv`, `idfa` and `attStatus`, so server-side integrations such as AppsFlyer can read them. The SDK owns those three keys and will overwrite any value your app has set on them. `reset()` and identifying a different user now keep the integration attributes that describe the device, such as the AppsFlyer and Adjust IDs, and drop the ones that describe the person, such as the Amplitude and Customer.io user IDs.
+- Fixes duplicate device attribute and subscription status change events being tracked when the subscription status is repeatedly set to the same logical state. As part of this, `subscriptionStatusDidChange` now fires only when the logical status changes — the status case, the set of entitlements, or an entitlement's `isActive` flag. Updates to transaction metadata such as expiry dates or renewal state no longer trigger it; use `customerInfoDidChange` for those.
+- Fixes subscribers with an unexpired subscription being reported as `inactive` on cold launch when the App Store has no purchases to report. Refunded and expired App Store subscriptions still deactivate immediately.
+- Fixes slow cold launches for subscribers on a weak network by no longer fetching their purchased products from StoreKit before the SDK is ready. Applies to StoreKit 2.
+- Fixes a data race during SDK configuration that Thread Sanitizer flagged on every launch.
+- Fixes a crash when `register` is called from more than one thread at a time.
+- Fixes a hang when identifying a different user after an install attribution match had been found.
+- Fixes issue where paying web users could end up having a temporary inactive subscription status if the server temporarily returns no entitlement data for them.
+- Fixes audiences matching users they shouldn't when you use a Purchase Controller.
+- Fixes paywall opens and purchases being reported under the wrong experiment when two campaigns share a paywall and a second placement fires while it is on screen.
+
 ## 4.16.3
 
 ### Fixes

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -72,6 +72,10 @@ When bumping the version, update all three files:
 3. `CHANGELOG.md` (add new version entry at top)
 
 - Follows semantic versioning
+- **Never use an `## Unreleased` heading in `CHANGELOG.md`.** Unreleased changes always live under the next concrete version number (e.g. `## 4.16.4`).
+- To pick that number, compare the version on `develop` with the version on `master`:
+  - If develop's version is **above** master's, a release is already staged — add your entries to that existing top section. Do not bump again.
+  - If develop's version **equals** master's, start the next release: add a new version section and bump all three files together (patch/minor/major per the change).
 
 ### Testing
 
@@ -110,3 +114,15 @@ When creating PRs, always include the checklist from `.github/PULL_REQUEST_TEMPL
 - [ ] I have run `swiftlint` in the main directory and fixed any issues.
 - [ ] I have updated the SDK documentation as well as the online docs.
 - [ ] I have reviewed the [contributing guide](https://github.com/superwall-me/paywall-ios/tree/master/.github/CONTRIBUTING.md)
+
+### Integration device identifiers
+
+AttributionFetcher refreshes IDFV/IDFA/ATT when setting integration attributes and
+on app activation after an integration has been configured. Compare the complete
+refreshed snapshot, not just provider IDs. Sync device values into user attributes
+(the server integration router reads those) only when that snapshot changes, since
+every sync costs a `user_attributes` event; explicit nulls clear stale IDs after
+ATT revocation. ATT is serialized as a numeric string in integration attributes.
+`idfv`, `idfa` and `attStatus` are SDK-owned user-attribute keys — document any
+change to that set in the changelog and the online docs. Don't gate the IDFA on
+the ATT status: `identifierForAdvertisers` already filters the all-zero id.
diff --git a/Examples/Advanced/Advanced/Info.plist b/Examples/Advanced/Advanced/Info.plist
@@ -17,7 +17,7 @@
 	</array>
 	<key>NSAppTransportSecurity</key>
 	<dict>
-		<key>NSAllowsArbitraryLoads</key>
+		<key>NSAllowsLocalNetworking</key>
 		<true/>
 	</dict>
 	<key>UIAppFonts</key>

diff --git a/Examples/Basic/Basic/Info.plist b/Examples/Basic/Basic/Info.plist
@@ -13,6 +13,11 @@
 			</array>
 		</dict>
 	</array>
+	<key>NSAppTransportSecurity</key>
+	<dict>
+		<key>NSAllowsLocalNetworking</key>
+		<true/>
+	</dict>
 	<key>UIAppFonts</key>
 	<array>
 		<string>Rubik-Regular.ttf</string>