Merge pull request #26 from adjust/v4290

Version 4.29.0

Author: uerceg

.gitignore

@@ -219,3 +219,5 @@ plugin/android/app/src/main/jniLibs
 
 test/android/.idea
 plugin/android/.idea
+plugin/ios/BuiltPlugin
+plugin/ios/libplugin_adjust.a

.gitmodules

@@ -6,3 +6,7 @@
 	path = ext/android/sdk
 	url = https://github.com/adjust/android_sdk.git
         branch = master
+[submodule "dist_directory"]
+	path = dist_directory
+	url = https://github.com/solar2d/com.adjust-plugin.adjust.git
+	branch = master

CHANGELOG.md

@@ -1,3 +1,28 @@
+### Version 4.29.0 (10th May 2021)
+#### Added
+- Added official support for Solar2D.
+- Added support for Apple Search Ads attribution with usage of `AdServices.framework`.
+- Added `appTrackingAuthorizationStatus` getter to `Adjust` API to be able to get current app tracking status.
+- Added improved measurement consent management and third party sharing system.
+- Added wrapper method `updateConversionValue` to `Adjust` API to allow updating `SKAdNetwork` conversion value via SDK API.
+- Added data residency feature. Support for EU and TR data residency region is added. To enable this feature, make sure to pass `"data-residency-eu"` or `"data-residency-tr"` as value of `urlStrategy` key when initialising Adjust SDK.
+- Added `setConversionValueUpdatedListener` method to `Adjust` API to allow setting of the callback which can be used to get information when Adjust SDK updates conversion value for the user.
+- Added possibility to pass `needsCost` key when initialising Adjust SDK to indicate if cost data is needed in attribution callback (by default cost data will not be part of attribution callback if not enabled with this setter method). Subsequently added new cost data fields in attribution callback - `costType`, `costAmount` and `costCurrency`.
+- Added support for new ways of preinstall tracking in Android. To enable this feature, make sure to pass `preinstallTrackingEnabled = true` when initialising Adjust SDK.
+- Added support for setting custom preinstall file location in Android. To enable this feature, make sure to pass your custom path as value of `preinstallFilePath` key when initialising Adjust SDK.
+
+#### Fixed
+- Fixed missing handling of `sku` parameter when performing subscription tracking in Android.
+
+#### Kudos
+- Huge kudos to @Shchvova for amazing help in this release with adding support for Solar2D as well adding support for new features from native SDKs to Corona SDK.
+
+#### Native SDKs
+- [[email protected]][android_sdk_v4.28.0]
+- [[email protected]][ios_sdk_v4.29.1]
+
+---
+
 ### Version 4.28.0 (3rd April 2021)
 #### Changed
 - Removed native iOS legacy code.
@@ -151,6 +176,7 @@
 [ios_sdk_v4.23.0]: https://github.com/adjust/ios_sdk/tree/v4.23.0
 [ios_sdk_v4.23.2]: https://github.com/adjust/ios_sdk/tree/v4.23.2
 [ios_sdk_v4.28.0]: https://github.com/adjust/ios_sdk/tree/v4.28.0
+[ios_sdk_v4.29.1]: https://github.com/adjust/ios_sdk/tree/v4.29.1
 
 [android_sdk_v4.12.0]: https://github.com/adjust/android_sdk/tree/v4.12.0
 [android_sdk_v4.12.1]: https://github.com/adjust/android_sdk/tree/v4.12.1
@@ -163,3 +189,4 @@
 [android_sdk_v4.24.0]: https://github.com/adjust/android_sdk/tree/v4.24.0
 [android_sdk_v4.24.1]: https://github.com/adjust/android_sdk/tree/v4.24.1
 [android_sdk_v4.27.0]: https://github.com/adjust/android_sdk/tree/v4.27.0
+[android_sdk_v4.28.0]: https://github.com/adjust/android_sdk/tree/v4.28.0

README.md

@@ -1,10 +1,11 @@
 ## Summary
 
-This is the Corona SDK of Adjust™. You can read more about Adjust™ at [adjust.com].
+This is the Adjust™ plugin for Solar2D (ex Corona SDK). You can read more about Adjust™ at [adjust.com].
 
 ## Table of contents
 
 * [Example app](#example-app)
+* [Simulator integration](#sim-integration)
 * [Basic integration](#basic-integration)
    * [Get the SDK](#sdk-get)
    * [Add the SDK to your app](#sdk-add)
@@ -24,7 +25,10 @@ This is the Corona SDK of Adjust™. You can read more about Adjust™ at [adjus
 * [Additional features](#additional-features)
    * [AppTrackingTransparency framework](#att-framework)
       * [App-tracking authorisation wrapper](#ata-wrapper)
+      * [Get current authorisation status](#ata-getter)
    * [SKAdNetwork framework](#skadn-framework)
+      * [Update SKAdNetwork conversion value](#skadn-value) 
+      * [Conversion value updated callback](#skadn-cv-updated-callback)
    * [Event tracking](#event-tracking)
       * [Revenue tracking](#revenue-tracking)
       * [Revenue deduplication](#revenue-deduplication)
@@ -61,13 +65,40 @@ This is the Corona SDK of Adjust™. You can read more about Adjust™ at [adjus
       * [Deeplinking on Android](#deeplinking-android)
       * [Deferred deeplinking scenario](#deeplinking-deferred)
       * [Reattribution via deeplinks](#deeplinking-reattribution)
+   * [Third-party sharing](#third-party-sharing)
+      * [Disable third-party sharing](#disable-third-party-sharing)
+      * [Enable third-party sharing](#enable-third-party-sharing)
+   * [Measurement consent](#measurement-consent)
+   * [[beta] Data residency](#data-residency)
 * [License](#license)
 
 
 ## <a id="example-app"></a>Example app
 
 There is example inside the [`plugin` directory][plugin]. In there in you can check how to integrate the Adjust SDK into your app.
 
+## <a id="sim-integration"></a>Simulator integration
+
+Easiest way to add Adjust plugin to your Simulator project is to add `build.settings` entry:
+
+```lua
+settings = 
+{
+    iphone =
+    {
+        plist =
+        {
+            NSUserTrackingUsageDescription = "This would allow the app to advertise better.",
+        },
+    },
+    plugins =
+    {
+        ['plugin.adjust'] = { publisherId = 'com.adjust' },
+    }
+}
+
+```
+
 ## <a id="basic-integration"></a>Basic integration
 
 These are the essential steps required to integrate the Adjust SDK into your Corona app project.
@@ -85,8 +116,8 @@ You can now add the Adjust SDK to your Corona Enterprise app project. The Adjust
 Inside your Android Studio app project, create a `libs` folder inside of your app folder and add the `plugin.adjust.jar` file to it. After that, please update your app's `build.gradle` file and add the following lines to your `dependencies` section:
 
 ```
-compile 'com.adjust.sdk:adjust-android:4.13.0'
-compile 'com.android.installreferrer:installreferrer:1.0'
+compile 'com.adjust.sdk:adjust-android:4.28.0'
+compile 'com.android.installreferrer:installreferrer:2.2'
 ```
 
 #### <a id="sdk-add-ios"></a>Add the SDK to your iOS project
@@ -196,7 +227,7 @@ In order to correctly attribute an install of your Android app to its source, Ad
 In order to support this in your app, please make sure that you have followed the [Add the SDK to your Android project](#sdk-add-android) chapter properly and that you have following line added to your `build.gradle` file:
 
 ```
-compile 'com.android.installreferrer:installreferrer:1.0'
+compile 'com.android.installreferrer:installreferrer:2.2'
 ```
 
 Also, make sure that you have paid attention to the [Proguard settings](#android-proguard) chapter and that you have added all the rules mentioned in it, especially the one needed for this feature:
@@ -233,11 +264,11 @@ As of v4.23.0, the Adjust SDK supports install tracking on Huawei devices with H
 
 You can add following iOS frameworks to your generated Xcode project to take advantage of additional features:
 
-* `iAd.framework` - in case you are running iAd campaigns
-* `AdSupport.framework` - for reading iOS Advertising Id (IDFA)
-* `CoreTelephony.framework` - for reading MCC and MNC information
-* `StoreKit.framework` - for communication with SKAdNetwork framework
-* `AppTrackingTransparency.framework` - to ask for user's consent to be tracked and obtain status of that consent
+* `iAd.framework` - needed for Apple Search Ads tracking
+* `AdServices.framework` - needed for Apple Search Ads tracking
+* `AdSupport.framework` - needed for reading iOS Advertising Id (IDFA)
+* `StoreKit.framework` - needed for communication with `SKAdNetwork` framework
+* `AppTrackingTransparency.framework` - needed to ask for user's consent to be tracked and obtain status of that consent
 
 ## <a id="additional-features"></a>Additional features
 
@@ -286,6 +317,30 @@ adjust.requestTrackingAuthorizationWithCompletionHandler(function(event)
 end)
 ```
 
+### <a id="ad-ata-getter"></a>Get current authorisation status
+
+**Note**: This feature exists only in iOS platform.
+
+To get the current app tracking authorization status you can call `appTrackingAuthorizationStatus` method of `Adjust` API that will return one of the following possibilities:
+
+* `0`: The user hasn't been asked yet
+* `1`: The user device is restricted
+* `2`: The user denied access to IDFA
+* `3`: The user authorized access to IDFA
+* `-1`: The status is not available
+
+To use this wrapper, you can call it as such:
+
+```lua
+local status = adjust.appTrackingAuthorizationStatus()
+print("[Adjust]: Authorization status = " .. status)
+if     status == "0" then print("[Adjust]: ATTrackingManagerAuthorizationStatusNotDetermined")
+elseif status == "1" then print("[Adjust]: ATTrackingManagerAuthorizationStatusRestricted")
+elseif status == "2" then print("[Adjust]: ATTrackingManagerAuthorizationStatusDenied")
+elseif status == "3" then print("[Adjust]: ATTrackingManagerAuthorizationStatusAuthorized")
+end
+```
+
 ### <a id="skadn-framework"></a>SKAdNetwork framework
 
 **Note**: This feature exists only in iOS platform.
@@ -305,6 +360,38 @@ adjust.create({
 })
 ```
 
+### <a id="skadn-value"></a>Update SKAdNetwork conversion value
+
+**Note**: This feature exists only in iOS platform.
+
+You can use Adjust SDK wrapper method `updateConversionValue` to update SKAdNetwork conversion value for your user:
+
+```lua
+adjust.updateConversionValue(6)
+```
+
+### <a id="skadn-cv-updated-callback"></a>Conversion value updated callback
+
+You can register callback to get notified each time when Adjust SDK updates conversion value for the user.
+
+```lua
+local function conversionValueUpdatedListener(event)
+    print("[Adjust]: Update conversion value: " .. event.message)
+end
+
+-- ...
+
+adjust.setConversionValueUpdatedListener(conversionValueUpdatedListener)
+
+-- ...
+
+adjust.create({
+    appToken = "{YourAppToken}",
+    environment = "SANDBOX",
+    logLevel = "VERBOSE",
+})
+```
+
 ### <a id="event-tracking"></a>Event tracking
 
 You can use Adjust to track all kinds of events. Let's say you want to track every tap on a button. If you create a new event token in your [dashboard] - let's say that event token is `abc123` - you can add the following line in your button’s click handler method to track the click:
@@ -639,6 +726,22 @@ In this case, the Adjust SDK not send the initial install session and any events
 
 **The maximum start time delay of the Adjust SDK is 10 seconds**.
 
+### <a id="needs-cost"></a>Needs cost
+
+To receive cost in attribution data you need to request it explicitly in `create` call
+```lua
+local adjust = require "plugin.adjust"
+
+adjust.create({
+    appToken = "{YourAppToken}",
+    environment = "SANDBOX",
+    logLevel = "VERBOSE",
+    needsCost = true
+})
+```
+
+If it is set to `true`, fields `costType`, `costAmount` and `costCurrency` would be set in the [attribution callback](#attribution-callback) event.
+
 ### <a id="attribution-callback"></a>Attribution callback
 
 You can register a listener to be notified of tracker attribution changes. Due to the different sources considered for attribution, this information cannot be provided synchronously. The simplest way to achieve this is to create a single anonymous listener which is going to be called **each time a user's attribution value changes**. Use the `setAttributionListener` method of the `adjust` instance to set the listener before starting the SDK:
@@ -658,6 +761,9 @@ local function attributionListener(event)
     print("Adgroup: " .. json_attribution.adgroup)
     print("Click label: " .. json_attribution.clickLabel)
     print("ADID: " .. json_attribution.adid)
+    print("Cost Type: " .. json_attribution.costType)
+    print("Cost Amount: " .. json_attribution.costAmount)
+    print("Cost Currency: " .. json_attribution.costCurrency)
 end
 
 -- ...
@@ -669,7 +775,9 @@ adjust.setAttributionListener(attributionListener)
 adjust.create({
     appToken = "{YourAppToken}",
     environment = "SANDBOX",
-    logLevel = "VERBOSE"
+    logLevel = "VERBOSE",
+    -- in case you want to get cost data in attribution callback
+    -- needsCost = true,
 })
 ```
 
@@ -683,6 +791,10 @@ Within the listener function you have access to the `attribution` parameters. He
 - `creative`        the creative grouping level of the current attribution
 - `clickLabel`      the click label of the current attribution
 - `adid`            the Adjust device identifier
+- `costType`        the cost type, use `needsCost` to request this value
+- `costAmount`      the price, use `needsCost` to request this value
+- `costCurrency`    the currency used, use `needsCost` to request this value
+
 
 Please make sure to consider our [applicable attribution data policies][attribution-data].
 
@@ -877,7 +989,6 @@ adjust.create({
 })
 ```
 
-
 ### <a id="gdpr-forget-me"></a>GDPR right to be forgotten
 
 In accordance with article 17 of the EU's General Data Protection Regulation (GDPR), you can notify Adjust when a user has exercised their right to be forgotten. Calling the following method will instruct the Adjust SDK to communicate the user's choice to be forgotten to the Adjust backend:
@@ -1203,11 +1314,85 @@ end
 
 Having added these calls, if the deeplink that opened your app contains any reattribution parameters, our SDK will pass that information to the backend, which will decide whether the user is going to be reattributed or not. As already mentioned, if a user gets reattributed, an attribution callback (if implemented) will be triggered with the new attribution value, and you will have this information in your app, as well.
 
+## <a id="third-party-sharing"></a>Third-party sharing for specific users
+
+You can notify Adjust when a user disables, enables, and re-enables data sharing with third-party partners.
+
+### <a id="disable-third-party-sharing"></a>Disable third-party sharing for specific users
+
+Call the following method to instruct the Adjust SDK to communicate the user's choice to disable data sharing to the Adjust backend:
+
+```lua
+adjust.trackThirdPartySharing({
+    enabled = false,
+})
+```
+
+Upon receiving this information, Adjust will block the sharing of that specific user's data to partners and the Adjust SDK will continue to work as usual.
+
+### <a id="enable-third-party-sharing">Enable or re-enable third-party sharing for specific users</a>
+
+Call the following method to instruct the Adjust SDK to communicate the user's choice to share data or change data sharing, to the Adjust backend:
+
+```lua
+adjust.trackThirdPartySharing({
+    enabled = true,
+})
+```
+
+Upon receiving this information, Adjust changes sharing the specific user's data to partners. The Adjust SDK will continue to work as expected.
+
+Call the following method to instruct the Adjust SDK to send the granular options to the Adjust backend:
+
+```csharp
+adjust.trackThirdPartySharing({
+    granularOptions = {
+        {
+            partnerName = "PartnerA",
+            key = "foo",
+            value = "bar",
+        },
+    },
+})
+```
+
+### <a id="measurement-consent"></a>Consent measurement for specific users
+
+You can notify Adjust when a user exercises their right to change data sharing with partners for marketing purposes, but they allow data sharing for statistical purposes. 
+
+Call the following method to instruct the Adjust SDK to communicate the user's choice to change data sharing, to the Adjust backend:
+
+```lua
+adjust.trackMeasurementConsent(true);
+```
+
+Upon receiving this information, Adjust changes sharing the specific user's data to partners. The Adjust SDK will continue to work as expected.
+
+### <a id="data-residency"></a>[beta] Data residency
+
+In order to enable data residency feature, make sure to set `urlStrategy` parameter when initialising Adjust SDK with one of the following constants:
+
+```lua
+local adjust = require "plugin.adjust"
+
+adjust.create({
+    appToken = "{YourAppToken}",
+    environment = "SANDBOX",
+    logLevel = "VERBOSE",
+    -- for EU data region
+    urlStrategy = "data-residency-eu"
+    -- or TR data region
+    -- urlStrategy = "data-residency-tr"
+})
+```
+
+**Note:** This feature is currently in beta testing phase. If you are interested in getting access to it, please contact your dedicated account manager or write an email to [email protected]. Please, do not turn this setting on before making sure with the support team that this feature is enabled for your app because otherwise SDK traffic will get dropped.
+
 ## <a id="license"></a>License
 
 The Adjust SDK is licensed under the MIT License.
 
-Copyright (c) 2012-2019 Adjust GmbH, http://www.adjust.com
+Copyright (c) 2012-2021 Adjust GmbH, http://www.adjust.com
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

VERSION

@@ -1 +1 @@
-4.28.0
+4.29.0