From c394a8d36e1aec186587dfc79dc370daa81d38d4 Mon Sep 17 00:00:00 2001 From: Wojtek Zieba Date: Fri, 19 Jan 2024 13:21:55 +0100 Subject: [PATCH 1/6] docs: first draft of the migration guide --- MIGRATION.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 MIGRATION.md diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..b72cc2c --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,67 @@ +# Parse.ly Android SDK Migration Guide + +This document acts as a guide for migration, detailing every breaking change that occurs between major versions of the Parse.ly Android SDK. + +## Upgrading to version 4.x + +When migrating to version 4.x of the Parse.ly Android SDK, you will encounter several changes that may require updates to your codebase. The following list details these breaking changes and recommended actions: + +### Removed `ParselyTracker#sharedInstace` methods + +Previously, the SDK was initialized `ParselyTracker#sharedInstace` method, which should be replaced with `ParselyTracker#init` method: + +```kotlin +ParselyTracker.sharedInstance("example.com", 30, this, true) // before + +ParselyTracker.init("example.com", 30, this, true) // now +``` + +The `ParselyTracker` was later accessed via a second variant of `ParselyTracker#sharedInstance`. All SDK methods are now available statically from `ParselyTracker`: + +```kotlin +ParselyTracker.sharedInstance().trackPageview("http://example.com/article1.html", "http://example.com/", null, null) // before + +ParselyTracker.trackPageview("http://example.com/article1.html", "http://example.com/", null, null) // now +``` + +*Action required*: Update how the Parsely SDK is initialized and accessed as presented above. + +### Removed methods or access restriction +The following methods have been removed from the `ParselyTracker` class: + +- `flushEventQueue` +- `getDebug` +- `queueSize` +- `storedEventsCount` +- `stopFlushTimer` + +The `toMap` methods that convert metadata objects to maps are no longer available for API consumers: + +- `ParselyMetadata#toMap` +- `ParselyVideoMetadata#toMap` + +*Action required*: Those methods shouldn't be needed to use the SDK. + +### Restricted access to internal API connection +`ParselyAPIConnection`, which might have been previously used for direct API interactions, is no longer accessible to the API consumer. + +*Action required*: Remove any code segments that interact with `ParselyAPIConnection` as this class is now an implementation detail of the SDK. + +### Non-nullable `urlRef` parameters +Parameters that were previously nullable when calling various tracking methods are now non-nullable. + +- In the `ParselyTracker` class, the `urlRef` parameter in the following methods requires a string value: + - `trackPageview` + - `startEngagement` + - `trackPlay` + +*Action required*: When calling these methods, ensure you provide a valid string. If there is no value available, pass an empty string `""` instead of `null`. + +### Debug configuration change +Configuring the debug mode during the SDK initialization has been simplified to a "dry run" mode flag. + +- The method `ParselyTracker#setDebug` is no longer available. + +*Action required*: When initializing the `ParselyTracker`, set the `dryRun` property to `true`. + +For clarification on any of these changes or assistance with migrating your code to the latest version of the Parse.ly Android SDK, please contact our support team. From 6b9742d1d428296320c6dfc7b5b5f31a215979ff Mon Sep 17 00:00:00 2001 From: Wojtek Zieba Date: Thu, 1 Feb 2024 12:49:58 +0100 Subject: [PATCH 2/6] docs: update migration guide with new changes --- MIGRATION.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index b72cc2c..87b973c 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -6,7 +6,7 @@ This document acts as a guide for migration, detailing every breaking change tha When migrating to version 4.x of the Parse.ly Android SDK, you will encounter several changes that may require updates to your codebase. The following list details these breaking changes and recommended actions: -### Removed `ParselyTracker#sharedInstace` methods +### Removed initialization `ParselyTracker#sharedInstace` methods Previously, the SDK was initialized `ParselyTracker#sharedInstace` method, which should be replaced with `ParselyTracker#init` method: @@ -16,31 +16,31 @@ ParselyTracker.sharedInstance("example.com", 30, this, true) // before ParselyTracker.init("example.com", 30, this, true) // now ``` -The `ParselyTracker` was later accessed via a second variant of `ParselyTracker#sharedInstance`. All SDK methods are now available statically from `ParselyTracker`: - -```kotlin -ParselyTracker.sharedInstance().trackPageview("http://example.com/article1.html", "http://example.com/", null, null) // before - -ParselyTracker.trackPageview("http://example.com/article1.html", "http://example.com/", null, null) // now -``` +Without prior initialization, the SDK will now throw `ParselyNotInitializedException` when accessing `ParselyTracker#sharedInstance`. *Action required*: Update how the Parsely SDK is initialized and accessed as presented above. ### Removed methods or access restriction -The following methods have been removed from the `ParselyTracker` class: +The following methods are no longer accessible from the `ParselyTracker` class: +- `engagementIsActive` - `flushEventQueue` +- `flushTimerIsActive` - `getDebug` +- `getEngagementInterval` +- `getFlushInterval` +- `getVideoEngagementInterval` - `queueSize` -- `storedEventsCount` - `stopFlushTimer` - -The `toMap` methods that convert metadata objects to maps are no longer available for API consumers: +- `storedEventsCount` +- `videoIsActive` + +Also, `toMap` methods are no longer available for API consumers: - `ParselyMetadata#toMap` - `ParselyVideoMetadata#toMap` -*Action required*: Those methods shouldn't be needed to use the SDK. +*Action required*: Those methods aren't needed to use the SDK. Remove any code segments that interact with them. ### Restricted access to internal API connection `ParselyAPIConnection`, which might have been previously used for direct API interactions, is no longer accessible to the API consumer. From 24ab2245498af7d32de735fb55082f9c705e8c57 Mon Sep 17 00:00:00 2001 From: Wojtek Zieba Date: Thu, 1 Feb 2024 14:29:37 +0100 Subject: [PATCH 3/6] docs: minor styling fix --- MIGRATION.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/MIGRATION.md b/MIGRATION.md index 87b973c..d5a0b31 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -62,6 +62,8 @@ Configuring the debug mode during the SDK initialization has been simplified to - The method `ParselyTracker#setDebug` is no longer available. -*Action required*: When initializing the `ParselyTracker`, set the `dryRun` property to `true`. +*Action required*: To enable `debug` mode, when initializing the `ParselyTracker`, set the `dryRun` property to `true`. + +--- For clarification on any of these changes or assistance with migrating your code to the latest version of the Parse.ly Android SDK, please contact our support team. From 2e3d9705f94fa684065a628de3307d39625e0bbb Mon Sep 17 00:00:00 2001 From: Wojtek Zieba Date: Thu, 1 Feb 2024 14:56:35 +0100 Subject: [PATCH 4/6] docs: link to migration guide from readme --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index 8533a9c..4f08a8e 100644 --- a/README.md +++ b/README.md @@ -18,3 +18,8 @@ implementation("com.parsely:parsely:") Full instructions and documentation can be found on the [Parse.ly help page](https://docs.parse.ly/android-sdk/). + +## Migration to 4.0.0 + +Version 4.0.0 of the SDK introduces significant updates and breaking changes that enhance performance and add new features. +These changes may require modifications to your existing code. For detailed instructions on how to adapt your code to these changes, please refer to our [Migration Guide](MIGRATION.md). From 3b16ce95e9e010370536d2d6af8d888ab1a6267e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wojciech=20Zi=C4=99ba?= Date: Thu, 1 Feb 2024 15:02:29 +0100 Subject: [PATCH 5/6] Update MIGRATION.md Co-authored-by: Ian Guedes Maia --- MIGRATION.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index d5a0b31..f61d520 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -6,9 +6,9 @@ This document acts as a guide for migration, detailing every breaking change tha When migrating to version 4.x of the Parse.ly Android SDK, you will encounter several changes that may require updates to your codebase. The following list details these breaking changes and recommended actions: -### Removed initialization `ParselyTracker#sharedInstace` methods +### Removed initialization `ParselyTracker#sharedInstance` methods -Previously, the SDK was initialized `ParselyTracker#sharedInstace` method, which should be replaced with `ParselyTracker#init` method: +Previously, the SDK was initialized `ParselyTracker#sharedInstance` method, which should be replaced with `ParselyTracker#init` method: ```kotlin ParselyTracker.sharedInstance("example.com", 30, this, true) // before From 46d44e267b013322f5b1b58b0006ed34273f4843 Mon Sep 17 00:00:00 2001 From: Wojtek Zieba Date: Thu, 1 Feb 2024 15:27:49 +0100 Subject: [PATCH 6/6] docs: clarify support contact points --- MIGRATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MIGRATION.md b/MIGRATION.md index f61d520..c80180d 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -66,4 +66,4 @@ Configuring the debug mode during the SDK initialization has been simplified to --- -For clarification on any of these changes or assistance with migrating your code to the latest version of the Parse.ly Android SDK, please contact our support team. +For clarification on any of these changes or assistance with migrating your code to the latest version of the Parse.ly Android SDK, please contact our support team at `support@parsely.com` or open a GitHub issue.