Add Swift SDK convenience methods to purchase presets document

articles/preset-errors.md

@@ -43,7 +43,7 @@ The Swift SDK ships with a convenience method for so you don't have to remember
 TelemetryDeck.errorOccurred(id: error.localizedDescription)
 ```
 
-The `errorOccurred` function also accepts the same arguments as the `signal` function (namely `parameters`, `floatValue`, `customUserID`) like the `signal` function in case you want to provide additional context info.
+The `errorOccurred` function also accepts the same arguments as the `signal` function (namely `parameters`, `floatValue`, `customUserID`) in case you want to provide additional context info.
 
 ## Separation of ID & Message
 

articles/preset-purchases.md

@@ -10,9 +10,9 @@ lead: TelemetryDeck ships with a set of insights that can be useful to track you
 
 ## Why Track Purchases?
 
-If you are offering In-App Purchases in your app, you might have noticed some delay in officially reported purchase stats. For example, App Store Connect charts do not offer any purchase data for the last 3 hours. Such a delay can be very annoying sometimes such as the day of your app launch or a specific live event related to your app. On top of that, App Store Connect in particular signs you out of your account very regularly, making it annoying to quickly look up purchase statistics.
+If you are offering In-App Purchases in your app, you might have noticed some delay in officially reported purchase stats. For example, App Store Connect charts do not offer any purchase data for the last 3 hours. Such a delay can be very annoying sometimes such as at the day of your app launch or a specific live event related to your app. On top of that, App Store Connect in particular signs you out of your account very regularly, making it annoying to quickly look up purchase statistics.
 
-That's why you might want to set up a signal in your application to track purchases in your app through TelemetryDeck within seconds, providing you with the live data you want.
+That's why you might want to set up a signal in your application to track purchases in your app through TelemetryDeck with just a couple of seconds delay, providing you with the live data you want.
 
 {% notewarning "Live Data vs. Correct Data" %}
 We do not offer any intelligence to correct once reported purchases, such as when users make refunds, or to detect subscription renewals. Therefore, our insights focus on more recent data. For longer-term or 100% correct data, refer to official sources.
@@ -21,47 +21,51 @@ We do not offer any intelligence to correct once reported purchases, such as whe
 
 ## Sending the Signal
 
-To report purchases to TelemetryDeck, send the event name `TelemetryDeck.Purchase.completed` with the `floatValue` parameter set to the USD amount the user purchased. For example, using the Swift SDK you can get the price from `StoreKit` like so:
+To report purchases to TelemetryDeck, send the event name `TelemetryDeck.Purchase.completed` with the `floatValue` parameter set to the USD amount the user purchased. For example, using the Swift SDK you can get the price from `StoreKit.Transaction` like so:
 
 ```swift
-let priceValue = NSDecimalNumber(decimal: storeKitProduct.price).doubleValue
+let priceValue = NSDecimalNumber(decimal: transaction.price ?? Decimal()).doubleValue
 
-TelemetryManager.send("TelemetryDeck.Purchase.completed", floatValue: priceValue)
+TelemetryDeck.signal("TelemetryDeck.Purchase.completed", floatValue: priceValue)
 ```
 
 {% notewarning "Converting Currencies" %}
 Make sure to convert any currencies to USD before sending them as signals. You can use [an API like this](https://www.exchangerate-api.com/docs/standard-requests) which offers 1,500 requests per month for free to get current exchange rates if needed. You could also fetch & hard-code them to your app for a rough estimate if you expect more than 1,500 purchases per month.
 {% endnotewarning %}
 
+The Swift SDK ships with a more convenient API that handles reading the price from the StoreKit transaction and converting to USD (with hard-coded non-live currency conversion) for you like so:
+
+```swift
+TelemetryDeck.purchaseCompleted(transaction: transaction)
+```
+
+{% noteinfo "Built-In Automatics" %}
+The `purchaseCompleted` convenience function in the Swift SDK also automates the extraction of the values explained in the next section. Optionally, it accepts the same arguments as the `signal` function (namely `parameters` and `customUserID`) in case you want to provide additional context info. The function is only available on iOS 15 or higher.
+{% endnoteinfo %}
+
 
 ## Attaching the Payload
 
 Optionally (but recommended), there are two additional payload keys that will give you additional insights:
 
 * `TelemetryDeck.Purchase.type`: Pass either `subscription` or `one-time-purchase` to see the type distribution.
 * `TelemetryDeck.Purchase.countryCode`: Pass the country code of the storefront to see the country distribution.
+* `TelemetryDeck.Purchase.currencyCode`: Pass the currency code of the storefront to see currency distribution.
 
 In Swift getting all values and sending them looks like this:
 
 ```swift
-let priceValue = NSDecimalNumber(decimal: storeKitProduct.price).doubleValue
-let purchaseType = storeKitProduct.subscription != nil ? "subscription" : "one-time-purchase"
-let countryCode = storeKitProduct.priceLocale.region?.identifier ?? "ZZ"
-
-TelemetryManager.send(
+TelemetryDeck.signal(
   "TelemetryDeck.Purchase.completed",
-  floatValue: priceValue,
-  with: [
-    "TelemetryDeck.Purchase.type": purchaseType,
-    "TelemetryDeck.Purchase.countryCode": countryCode
-  ]
+  parameters: [
+    "TelemetryDeck.Purchase.type": transaction.subscriptionGroupID != nil ? "subscription" : "one-time-purchase",
+    "TelemetryDeck.Purchase.countryCode": transaction.storefront.countryCode,
+    "TelemetryDeck.Purchase.currencyCode": transaction.currency?.identifier ?? "???"
+  ],
+  floatValue: NSDecimalNumber(decimal: transaction.price ?? Decimal()).doubleValue
 )
 ```
 
-{% noteinfo "3rd-Party Services" %}
-> If you are using a third-party service like RevenueCat, you can access the `SKProduct` type on their own types. For example, on RevenueCat's `Package` type, you would call `.storeProduct.skProduct`.
-{% endnoteinfo %}
-
 
 ## Effect on Privacy & App Tracking Transparency