Merge pull request #41 from adjust/v4290

Version 4.29.0

CHANGELOG.md

@@ -1,3 +1,24 @@
+### Version 4.29.0 (14th September 2021)
+#### Added
+- Added possibility to get cost data information in attribution callback.
+- Added `setNeedsCost` method to `AdjustConfig2dx` 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).
+- Added `setPreinstallTrackingEnabled` method to `AdjustConfig2dx` to allow enabling of preinstall tracking (this feature is OFF by default).
+- Added support for Apple Search Ads attribution with usage of `AdServices.framework`.
+- Added `setAllowAdServicesInfoReading` method to `AdjustConfig2dx` to allow option for users to prevent SDK from performing any tasks related to Apple Search Ads attribution with usage of `AdServices.framework`.
+- Added `setAllowiAdInfoReading` method to `AdjustConfig2dx` to allow option for users to prevent SDK from performing any tasks related to Apple Search Ads attribution with usage of `iAd.framework`.
+- Added wrapper method `updateConversionValue` method to `Adjust2dx` to allow updating SKAdNetwork conversion value via SDK API.
+- Added `getAppTrackingAuthorizationStatus` getter to `Adjust2dx` instance to be able to get current iOS app tracking status.
+- Added improved measurement consent management and third party sharing mechanism.
+- Added data residency feature. You can choose this setting by calling `setUrlStrategy` method of `AdjustConfig2dx` instance with `AdjustDataResidencyEU` (for EU data residency region), `AdjustDataResidencyTR` (for TR data residency region) or `AdjustDataResidencyUS` value (for US data residency region).
+- Added `setConversionValueUpdatedCallback` method to `AdjustConfig2dx` which can be used to set a callback which will get information when Adjust SDK updates conversion value for the user.
+- Added preinstall tracking with usage of system installer receiver on Android platform (`setPreinstallFilePath` method of the `AdjustConfig2dx`).
+
+#### Native SDKs
+- [[email protected]][ios_sdk_v4.29.6]
+- [[email protected]][android_sdk_v4.28.4]
+
+---
+
 ### Version 4.28.0 (3rd April 2021)
 #### Changed
 - Removed native iOS legacy code.
@@ -348,6 +369,8 @@
 [ios_sdk_v4.22.1]: https://github.com/adjust/ios_sdk/tree/v4.22.1
 [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.6]: https://github.com/adjust/ios_sdk/tree/v4.29.6
 
 [android_sdk_v4.0.8]: https://github.com/adjust/android_sdk/tree/v4.0.8
 [android_sdk_v4.1.0]: https://github.com/adjust/android_sdk/tree/v4.1.0
@@ -368,5 +391,7 @@
 [android_sdk_v4.22.0]: https://github.com/adjust/android_sdk/tree/v4.22.0
 [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.4]: https://github.com/adjust/android_sdk/tree/v4.28.4
 
 [windows_sdk_v4.0.3]: https://github.com/adjust/windows_sdk/tree/v4.0.3

README.md

@@ -25,7 +25,10 @@ This is the Cocos2d-x SDK of Adjust™. You can read more about Adjust™ at [Ad
 * [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-update-conversion-value)
+      * [Conversion value updated callback](#skadn-cv-updated-callback)
    * [Event tracking](#event-tracking)
       * [Revenue tracking](#revenue-tracking)
       * [Revenue deduplication](#revenue-deduplication)
@@ -51,6 +54,7 @@ This is the Cocos2d-x SDK of Adjust™. You can read more about Adjust™ at [Ad
       * [Google Play Services advertising identifier](#di-gps-adid)
       * [Amazon advertising identifier](#di-fire-adid)
       * [Adjust device identifier](#di-adid)
+   * [Set external device ID](#set-external-device-id)
    * [User attribution](#user-attribution)
    * [Push token](#push-token)
    * [Pre-installed trackers](#pre-installed-trackers)
@@ -59,6 +63,7 @@ This is the Cocos2d-x SDK of Adjust™. You can read more about Adjust™ at [Ad
       * [Deferred deep linking](#deeplinking-deferred)
       * [Deep link handling for iOS apps](#deeplinking-ios)
       * [Deep link handling for Android apps](#deeplinking-android)
+   * [Data residency](#data-residency)
 * [License](#license)
 
 ## <a id="basic-integration"></a>Basic integration
@@ -86,7 +91,8 @@ $(LOCAL_PATH)/../../../Classes/Adjust/AdjustEventSuccess2dx.cpp \
 $(LOCAL_PATH)/../../../Classes/Adjust/AdjustSessionFailure2dx.cpp \
 $(LOCAL_PATH)/../../../Classes/Adjust/AdjustSessionSuccess2dx.cpp \
 $(LOCAL_PATH)/../../../Classes/Adjust/AdjustAppStoreSubscription2dx.cpp \
-$(LOCAL_PATH)/../../../Classes/Adjust/AdjustPlayStoreSubscription2dx.cpp
+$(LOCAL_PATH)/../../../Classes/Adjust/AdjustPlayStoreSubscription2dx.cpp \
+$(LOCAL_PATH)/../../../Classes/Adjust/AdjustThirdPartySharing2dx.cpp
 ```
 
 ### <a id="sdk-project-settings"></a>Adjust project settings
@@ -146,7 +152,7 @@ After this, open the `AndroidManifest.xml` file of your Android project and add
 If you are using Proguard, add these lines to your Proguard file:
 
 ```
--keep public class com.adjust.sdk.** { *; }
+-keep class com.adjust.sdk.** { *; }
 -keep class com.google.android.gms.common.ConnectionResult {
     int SUCCESS;
 }
@@ -171,7 +177,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 to add following dependency to your `build.gradle` file:
 
 ```
-implementation 'com.android.installreferrer:installreferrer:1.0'
+implementation '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:
@@ -210,16 +216,13 @@ As of v4.22.0, the Adjust SDK supports install tracking on Huawei devices with H
 
 ### <a id="ios-frameworks"></a>[iOS] Frameworks
 
-You need to add following frameworks to your app's Xcode project:
+Select your project in the Project Navigator. In the left hand side of the main view, select your target. In the tab `Build Phases`, expand the group `Link Binary with Libraries`. On the bottom of that section click on the `+` button. Select below mentined frameworks and make sure to change the `Status` of frameworks to `Optional`. Adjust SDK uses these frameworks with following purpose:
 
-* `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
+* `iAd.framework` - to support Apple Search Ads campaigns
+* `AdServices.framework` - to support Apple Search Ads campaigns
+* `AdSupport.framework` - to read iOS Advertising Id (IDFA) value
+* `StoreKit.framework` - to communicate with `SKAdNetwork` framework
 * `AppTrackingTransparency.framework` - to ask for user's consent to be tracked and obtain status of that consent
-* `AdjustSdk.framework` - our native iOS SDK framework
-
-If you are not running any iAd campaigns, you can feel free to remove the `iAd.framework` dependency. If you don't use SKAdNetwork framework, feel free to remove `StoreKit.framework` dependency (unless you need it for something else).
 
 ### <a id="ios-linker-flags"></a>[iOS] Additional linker flags
 
@@ -376,6 +379,18 @@ static void authorizationStatusCallback(int status) {
 Adjust2dx::requestTrackingAuthorizationWithCompletionHandler(authorizationStatusCallback);
 ```
 
+### <a id="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 `getAppTrackingAuthorizationStatus` method of `Adjust2dx` class 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
+
 ### <a id="skadn-framework"></a>SKAdNetwork framework
 
 **Note**: This feature exists only in iOS platform.
@@ -388,6 +403,47 @@ In case you don't want the Adjust SDK to automatically communicate with SKAdNetw
 adjustConfig.deactivateSKAdNetworkHandling();
 ```
 
+### <a id="skadn-update-conversion-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:
+
+```js
+Adjust2dx::updateConversionValue(6);
+```
+
+### <a id="skadn-cv-updated-callback"></a>Conversion value updated callback
+
+**Note**: This feature exists only in iOS platform.
+
+You can register callback to get notified each time when Adjust SDK updates conversion value for the user.
+
+```cpp
+#include "Adjust/Adjust2dx.h"
+
+// ...
+
+static void conversionValueUpdatedCallbackMethod(int conversionValue) {
+    CCLOG("\nConversion value updated!");
+    CCLOG("\nConversion value: %d", conversionValue);
+}
+
+// ...
+
+bool AppDelegate::applicationDidFinishLaunching() {
+    std::string appToken = "{YourAppToken}";
+    std::string environment = AdjustEnvironmentSandbox2dx;
+
+    AdjustConfig2dx adjustConfig = AdjustConfig2dx(appToken, environment);
+    adjustConfig.setLogLevel(AdjustLogLevel2dxVerbose);
+    adjustConfig.setConversionValueUpdatedCallback(conversionValueUpdatedCallbackMethod);
+    Adjust2dx::start(adjustConfig);
+
+    // ...
+}
+```
+
 ### <a id="event-tracking"></a>Event tracking
 
 With Adjust, you can track any event that you want. 
@@ -668,6 +724,9 @@ The callback function will be called when the SDK receives the final attribution
 - `std::string creative` the creative grouping level of the current attribution.
 - `std::string clickLabel` the click label of the current attribution.
 - `std::string adid` the Adjust device identifier.
+- `std::string costType` the cost type.
+- `double costAmount` the cost amount.
+- `std::string costCurrency` the cost currency.
 
 ```cpp
 #include "Adjust/Adjust2dx.h"
@@ -685,6 +744,9 @@ static void attributionCallbackMethod(AdjustAttribution2dx attribution) {
     CCLOG("\nCreative: %s", attribution.getCreative().c_str());
     CCLOG("\nClick label: %s", attribution.getClickLabel().c_str());
     CCLOG("\nAdid: %s", attribution.getAdid().c_str());
+    CCLOG("\nCost type: %s", attribution.getCostType().c_str());
+    CCLOG("\nCost amount: %f", attribution.getCostAmount());
+    CCLOG("\nCost currency: %s", attribution.getCostCurrency().c_str());
     CCLOG("\n");
 }
 
@@ -705,6 +767,8 @@ bool AppDelegate::applicationDidFinishLaunching() {
 
 Please make sure to consider the [applicable attribution data policies][attribution-data].
 
+**Note**: The cost data - `costType`, `costAmount` & `costCurrency` are only available when configured in `AdjustConfig2dx` by calling `setNeedsCost` method. If not configured or configured, but not being part of the attribution, string fields will have value `null` and double field will be 0. This feature is available in SDK v4.29.0 and above.
+
 ### <a id="session-event-callbacks"></a>Session and event callbacks
 
 You can register a callback to be notified of successfully tracked, as well as failed, events and/or sessions.
@@ -1005,6 +1069,32 @@ std::string adid = Adjust2dx::getAdid();
 
 **Note**: Information about the **adid** is only available after the Adjust backed has tracked your app's installation. From that moment on, the Adjust SDK has information about the device **adid** and you can access it with this method. So, **it is not possible** to access the **adid** before the SDK has been initialized and the installation of your app has been tracked successfully.
 
+### <a id="set-external-device-id"></a>Set external device ID
+
+> **Note** If you want to use external device IDs, please contact your Adjust representative. They will talk you through the best approach for your use case.
+
+An external device identifier is a custom value that you can assign to a device or user. They can help you to recognize users across sessions and platforms. They can also help you to deduplicate installs by user so that a user isn't counted as multiple new installs.
+
+You can also use an external device ID as a custom identifier for a device. This can be useful if you use these identifiers elsewhere and want to keep continuity.
+
+Check out our [external device identifiers article](https://help.adjust.com/en/article/external-device-identifiers) for more information.
+
+> **Note** This setting requires Adjust SDK v4.22.0 or later.
+
+To set an external device ID, assign the identifier to the `externalDeviceId` property of your config instance. Do this before you initialize the Adjust SDK.
+
+```cpp
+AdjustConfig2dx adjustConfig = AdjustConfig2dx(appToken, environment);
+adjustConfig.setExternalDeviceId("{Your-External-Device-Id}");
+Adjust2dx::adjustConfig(config);
+```
+
+> **Important**: You need to make sure this ID is **unique to the user or device** depending on your use-case. Using the same ID across different users or devices could lead to duplicated data. Talk to your Adjust representative for more information.
+
+If you want to use the external device ID in your business analytics, you can pass it as a session callback parameter. See the section on [session callback parameters](#session-callback-parameters) for more information.
+
+You can import existing external device IDs into Adjust. This ensures that the backend matches future data to your existing device records. If you want to do this, please contact your Adjust representative.
+
 ### <a id="user-attribution"></a>User attribution
 
 Attribution callbacks are triggered via the method described in the [attribution callback section](#attribution-callback). They provide you with information about any changes to your users’ attribution values. If you wish to access information about a user's current attribution value at any other time, you can make a call to the following method of the `Adjust2dx` instance:
@@ -1110,6 +1200,16 @@ To set up your iOS app to handle deep linking at a native level, please follow o
 
 To set up your Android app to handle deep linking at a native level, please follow our [guide][android-deeplinking] in the official Android SDK README.
 
+### <a id="data-residency"></a>Data residency
+
+In order to enable data residency feature, make sure to call `setUrlStrategy` method of the `AdjustConfig2dx` instance with one of the following constants:
+
+```js
+adjustConfig.setUrlStrategy(AdjustDataResidencyEU); // for EU data residency region
+adjustConfig.setUrlStrategy(AdjustDataResidencyTR); // for Turkey data residency region
+adjustConfig.setUrlStrategy(AdjustDataResidencyUS); // for US data residency region
+```
+
 
 [adjust]:       http://adjust.com
 [dashboard]:    http://adjust.com
@@ -1138,7 +1238,7 @@ To set up your Android app to handle deep linking at a native level, please foll
 
 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

VERSION

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

dist/ADJAdjust2dx.h

@@ -14,6 +14,7 @@
 #include "ADJEvent2dx.h"
 #include "ADJConfig2dx.h"
 #include "ADJAppStoreSubscription2dx.h"
+#include "ADJThirdPartySharing2dx.h"
 #include "AdjustAttribution2dx.h"
 
 extern const std::string ADJEnvironmentSandbox2dx;
@@ -46,6 +47,10 @@ class ADJAdjust2dx {
     static std::string getSdkVersion();
     static AdjustAttribution2dx getAttribution();
     static void requestTrackingAuthorizationWithCompletionHandler(void (*trackingStatusCallback)(int status));
+    static int getAppTrackingAuthorizationStatus();
+    static void trackThirdPartySharing(ADJThirdPartySharing2dx thirdPartySharing);
+    static void trackMeasurementConsent(bool measurementConsent);
+    static void updateConversionValue(int conversionValue);
     // For testing purposes only.
     static void setTestOptions(std::map<std::string, std::string> testOptionsMap);
     static void teardown();