diff --git a/docs/main/updating/plugins/3-0.md b/docs/main/updating/plugins/3-0.md index f40412894..2ea12bd5e 100644 --- a/docs/main/updating/plugins/3-0.md +++ b/docs/main/updating/plugins/3-0.md @@ -12,7 +12,7 @@ There are several required and recommended changes for plugins that are being up It is currently difficult for the core team to make changes to the internals of Capacitor without potentially affecting plugins. Because most classes and methods in Capacitor 2 are public for both iOS and Android, we have observed undesired usage of Capacitor APIs that we considered internal. -During Capacitor 3 development, we will be evaluating this problem and creating an official public API for plugins, which will be [documented here](/docs/core-apis). +During Capacitor 3 development, we will be evaluating this problem and creating an official public API for plugins, which will be [documented here](/docs/v3/core-apis). ## Android @@ -129,7 +129,7 @@ if let isSim = bridge?.isSimEnvironment, isSim { In addition to the reference changing from `strong` to `weak`, the API of the bridge itself has been updated (it is now exposed via a more formal protocol). Many of the properties and methods have been renamed but backwards support exists where possible by preserving and deprecating the old interfaces. Xcode will be able to automatically suggest the newer replacement in most cases. You should migrate any existing code so your plugin can build without compiler warnings. -![Xcode autocorrect suggestion](../../../../static/img/v4/docs/ios/bridge-naming-migration.png) +![Xcode autocorrect suggestion](../../../../static/img/v3/docs/ios/bridge-naming-migration.png) ### `CAPPluginCall` Parameters @@ -138,7 +138,7 @@ Capacitor includes a collection of convenience methods (`getString`, `getDate`, - `get()` has been removed. If you want to access the arguments directly, read the `options` dictionary. - `hasOption` has been deprecated. Use one of the typed accessors to check for a value. - Any accessor that takes a default value now requires a non-optional default but returns a non-optional result. This can change the optionality of your local variables but should reduce the usage of force unwrapping, which is an anti-pattern in Swift. -- The behavior around dates and null values has been slightly changed and better documented. [Find more information here](/docs/core-apis/data-types#ios). +- The behavior around dates and null values has been slightly changed and better documented. [Find more information here](/docs/v3/core-apis/data-types#ios). - The Obj-C convenience accessors have been split out to avoid conflicts with the Swift implementations. If you are working in Obj-C, you will need to import them separately by adding `#import ` to your `.m` file. ## Changes to `PluginCall` & `CAPPluginCall` @@ -153,7 +153,7 @@ Previously, calling `resolve()` with no arguments resulted in an empty object be ### Saving calls -The `save()` method has deprecated and a replacement `keepAlive` property has been added. The recommended patterns for saving a call have been documented to clarify the behavior. [Read more about that here](/docs/core-apis/saving-calls). +The `save()` method has deprecated and a replacement `keepAlive` property has been added. The recommended patterns for saving a call have been documented to clarify the behavior. [Read more about that here](/docs/v3/core-apis/saving-calls). ### Set iOS deployment target to 12.0 @@ -215,7 +215,7 @@ We are now recommending that plugin authors make use of the new error codes in C - **Unavailable**: indicates the functionality can't be used right now - **Unimplemented**: indicates the functionality can't or won't be implemented, or may be implemented in the future -Read more about Error Handling for [Web](/docs/plugins/web#error-handling), [iOS](/docs/plugins/ios#error-handling), and [Android](/docs/plugins/android#error-handling). +Read more about Error Handling for [Web](/docs/v3/plugins/web#error-handling), [iOS](/docs/v3/plugins/ios#error-handling), and [Android](/docs/v3/plugins/android#error-handling). ## Adopting the new Permissions API @@ -225,4 +225,4 @@ One goal of Capacitor 3 is to give app developers the ability to request or chec It is perfectly fine to continue automatically requesting permissions, but you are encouraged to adopt the new permissions pattern as well to give app developers control over permissions. -[Learn how to implement the Permissions API in your plugin ›](/docs/plugins/web#permissions) +[Learn how to implement the Permissions API in your plugin ›](/docs/v3/plugins/web#permissions) diff --git a/docs/main/updating/plugins/4-0.md b/docs/main/updating/plugins/4-0.md new file mode 100644 index 000000000..19ab576f2 --- /dev/null +++ b/docs/main/updating/plugins/4-0.md @@ -0,0 +1,79 @@ +--- +title: Updating plugins to 4.0 +description: Guide for updating a Capacitor v3 plugin to v4 +slug: /updating/plugins/4-0 +--- + +# Updating a Capacitor v3 plugin to 4.0 + +There are only a few changes required to update a plugin from Capacitor 3 to Capacitor 4. + +:::info +While you can follow the manual steps below, check out [this tool](https://github.com/rdlabo-team/capacitor-plugin-to-v4) from community member [@rdlabo](https://twitter.com/rdlabo) that automatically updates a Capacitor 3 plugin to v4. +::: + +## Android + +### Update Android Project Variables + +In your `build.gradle` file, update your values to the following new minimums: + +```groovy +minSdkVersion = 22 +compileSdkVersion = 32 +targetSdkVersion = 32 +androidxAppCompatVersion = '1.4.2' +junitVersion = '4.13.2' +androidxJunitVersion = '1.1.3' +androidxEspressoCoreVersion = '3.4.0' +``` + +### Update to Gradle 7 + +Adjust your Gradle project settings in `File > Project Structure > Project`. The Android Gradle Plugin Version should be 7.2.1 or later and the Gradle Version should be 7.4.2 or later. Apply these changes and run a gradle sync by clicking on the Elephant Icon in the top right of Android Studio. + +:::info +Android Studio may provide an automatic migration to Gradle 7. Go ahead and take them up on the offer! To upgrade, go to your `build.gradle` file, and click on the 💡 icon, and click "Upgrade Gradle. Once your project is migrated over, run a gradle sync as described above. + +Another alternative would be to use the Android Gradle Plugin Upgrade Assistant to handle the migration for you. Steps for this tool can be found in the [Android documentation](https://developer.android.com/studio/build/agp-upgrade-assistant). +::: + +### Ensure you are using Java 11 + +Capacitor 3 works with both Java 8 and Java 11. Moving forward, Capacitor 4 will only support Java 11. You can change this in your project by going to the following menu in Android Studio: + +`Preferences > Build, Execution, Deployment > Build Tools > Gradle` + + + +From there, you can modify the "Gradle JDK" to be Java 11. + +:::info +Java 11 ships with the latest version of Android Studio. No additional downloads needed! +::: + +### Remove `jcenter()` from the Gradle files + +In previous Capacitor versions, `jcenter()` was required due to our Cordova compatibility layer being hosted on Jcenter. However, we are now using the latest Cordova Android version, hosted on Maven Central. With this, you may be able to remove `jcenter()` entirely from your `build.gradle` file. If you are using other native dependencies, make sure they aren't hosted on Jcenter before removing it! + + +## iOS + +### Raise iOS Deployment Target + +Do the following to your Xcode project: select the **Project** within the project editor and open the **Build Settings** tab. Under the **Deployment** section, change **iOS Deployment Target** to **iOS 13.0**. Repeat the same steps for any app **Targets**. + +Then, open `ios/App/Podfile` and update the iOS version to 13.0: + +```ruby +platform :ios, '13.0' +``` + +Next, update the `podspec` file at the root of the project: + +``` +s.ios.deployment_target = '13.0' +``` diff --git a/sidebars.js b/sidebars.js index cd4483dd1..d89356b4c 100644 --- a/sidebars.js +++ b/sidebars.js @@ -34,7 +34,8 @@ module.exports = { 'main/updating/3-0', 'main/updating/2-0', 'main/updating/1-1', - 'main/updating/plugins/3-0', + 'main/updating/plugins/4-0', + 'main/updating/plugins/3-0' ], }, {