How Capacitor Migrates Cordova Plugins

like cordova capacity comes with its own plugins to use to access native functionality some of which are included by default with capacitor and some of which are created by the community and shared with other developers however capacitor is a much younger project than cordova and many people rely on plugins that are only available in the cordova ecosystem unfortunately for those of us who want to use capacitor but still want to use those cordova plug-ins most cordover plug-ins are compatible with capacitor by default a lot of the time it is as simple as running npm install and then the plug-in that you want to use and you'll be able to just use that cordover plug-in in your capacitive project so capacitor does an excellent job of automatically migrating cordova plug-ins to capacitor in most cases however some plug-ins will not work by default without additional configuration and there are some plugins that are just not compatible and won't work with capacitor for a list of plugins that are currently known to not be compatible i'll have a link in the description that you can check out so in this video we're going to do a technical walkthrough of how capacitor automatically migrates a cordova plug-in so the main benefit of understanding this process is that it becomes more clear what you need to do to finish manually migrating a cordover plug-in to capacitor let's say you install a cordova plug-in and it doesn't work you will have a sort of means of investigation for figuring out why that is and how to fix it and aside from that for some people the technical details of how this process uh process works might just be interesting and it might end up being useful in other ways we'll be focusing on android specifically in this video okay so let's get started i have the cordova plug-in facebook 4 plugin up on screen right now so this is the one we're just using as a as an example to run through how the migration works i also have a written blog post that covers this same plugin if you're interested in reading that so basically we're just going to go through this step by step how we're going to install this and then just walk through what is happening so to get started what we're going to do is install this uh plug-in into a capacitor project so all we need to do is run npm install and then the name of our plug-in cordova plug-in facebook for or hit and still and the reason we are using this plug-in specifically is because it's a reasonably complex plug-in and it also makes use of these cordova uh install variables which cause us a bit of trouble when we're trying to use plugins in capacitor but we will talk about how to get around that okay now that has finished installing we're just going to run np npx cap sync and that is going to pull that plug-in over into the native project uh it is worth keeping in mind that i've already set up capacitor in this project and i've also already added the android platform to the project as well now if you're unsure on how to complete those steps capacitor i'll also link to the basic getting started documentation in the description as well okay so that's completed now and if you look at the messages here you can see that it's found that plugin that we've installed so we know it's getting pulled over into our native project and if we just quickly bring up android studio we don't really have any context for what is happening on capacitors side of things yet and we're going to take a much more structured approach to this but if we just go searching through our project we can actually find where that plug-in was installed so if you open up the project files here expand our android we can see something called capacitor cordova android plugins and so that's probably a good place to start and if we just expand this out keep opening all these files eventually we will find a reference to facebook here we have org.apache.cordova.facebook then we have connect plugin and this is the native android code for the plugin itself so let's just quickly open that up just have a peek at it and what you see in here is just java code that is going to be integrating with that facebook sdk and this is what uh our application is going to be communicating with so from our application in the web view we'll make it call using a javascript api which will eventually call these methods in the native code and then send us back the results so you can see here we have things like on resume on pause there's probably some login methods in here somewhere some game request dialogues uh let me just do a search here for i think it's um get login status is one of the methods that this plugin provides so you can see that methods being provided here through this execute method so that's not too important we don't really need to worry about this too much because you don't usually need to do anything with the the native code here we'll just use the cordova plugin as per normal uh when we're using in our application but we can see that that plugin has been pulled into this project but if we try to run this right now it's not going to work because we are missing those install variables which configure your facebook app id and things like that so it won't work uh but you might be left at this point thinking well what do i do it's worth noting that when you run np mpx capsync it'll often have warning messages that pop up for things that the native projects require so it'll have sometimes information in here that you can just copy and paste to get everything configured but not always and we don't get any messages like that for android here so what we're going to do then is take a look at this uh cordova plug-in facebook for project itself the actual plugin files and what we can do is open up the plugin.xml file and this file is basically instructions for cordova on how to configure the plugin correctly for the native platforms uh but this file is also what capacitor uses to migrate the plugin over and basically what happens in here is all the different entries we have in here serve as instructions for how to configure this in the native code so we can kind of follow along and see what's happening where it's happening and what is missing when capacitor tries to set it up and so you'll see a few different xml tags in here we're going to focus specifically on stuff contained within platform name equals android because this is the instructions for android specifically and you'll see in here we have things like js module config file source file framework so these are all different types of instructions that capacitor is interpreting and it's important to remember that these are essentially instructions for cordova this isn't how capacitor works but capacitor is able to interpret this to migrate the cordover plug-in over to capacitor so what we're going to do is just go through step by step here see what the plugin.xml file is expecting to happen and then we'll inspect our native android project and see what is actually happening and whether we need to step in and configure some things ourselves so before we get started i just want to give you a little tip on how to find out what all this stuff does this isn't the kind of information you'll find in the documentation at least not yet so a good way to find out what exactly is happening is to just look at the source code for a capacitor yourself and that might sound a bit intimidating if you're not used to doing that kind of thing but what we can do for example if i'm looking at this and i'm trying to figure out what does the js module do what what does this mean exactly and so what i could do is i could just see what capacitor is doing when it's using that so if i search for js module in the capacitor github repository i can see what it pulls up and you can see here in the plugin.ts file it's making a reference to js module if i pull up config file for example i can see that there is another file where that's being referenced in uh the cli forward slash source forward slash cordova so you can just open these various files up and then you can see what is happening so it might be a bit hard to to figure out exactly or quickly but you can sort of step through this code and try to figure out what is happening with those plugin.xml entries and usually it's just a matter of looking at this code and then that will call some method we have plug-in entries here we can see that's an array so then we could then see what happens with plug-in entries somewhere else in the code and it ends up being this long sort of daisy chain of different things you end up following along but you can figure out quite a lot on your own if you you know stick with it kind of thing so i'm not going to show you what's happening in the capacitor code for every step along the way here because uh it would just take far too long so i've already sort of done that research side of things myself so i'm just going to talk through at a more high level what's happening here and we'll reference our android studio project as well where necessary so this js module entry here with clobbers which is a pretty weird tag name but what this means basically is this is the code that provides the api for the plugin so if we actually take a look at facebooknative.js i'm going to open this up in um it's in a separate tab here from the cordover plugin facebook for repository so that was referencing www forward slash facebook native.js so let's just have a quick look at that and what you'll see here is this is a file that is exporting various methods and these methods are the methods that we use to interact with this plugin like get login status login check has correct permissions log out api so this is what we would actually be using in our application so this is providing the methods to the browser that we will be able to use so what this instruction here means is that we want to grab that file and then we want to set it up on the facebook connect plugin name space and so what that means is that it'll be available through window.facebookconnect plugin and that's how you would interact with the plugin if you're just using the default cordova uh way of using it if you're using something like ionic native that would then be wrapped and you'd use it in a different way but we won't worry about that for now so basically this is just setting up those methods in the browser and what capacitor will do i guess this is a pretty easy instruction for capacitor to interpret it'll just take that javascript file and it will inject it into the webview for capacitor and that will make it available to us as well so next up we have the config file entry here and what this means basically is we're trying to provide some kind of xml configuration here and in cordova's case it would be adding this xml to res forward slash xml forward slash config.xml and this isn't exactly what capacitor does what capacitor will do basically is look for any config file tag that has a target that includes config.xml and it will put them all in the same uh the same file and you'll be able to find this firewire app source main res xml and then config.xml so you can see here that this xml has already been added this feature section here has now been copied into our config.xml file but one thing you will clearly notice is that it didn't include all of these access origin tags here so an important part of what capacitor does here is it will only copy over these feature tags so anything else is going to get ignored and so this is where it's important to understand this process because all of this stuff isn't going to get copied over and if this is important how the plugin works then this might be something that we need to configure ourselves manually in the native project now in the case of the facebook plugin it's not required since we already have a wildcard access origin here anyway none of these should matter because they're going to be allowed and this sets a android min sdk version of 15 and i believe the capacitor min sdk version is already 21 anyway so that's not going to make a difference either however there might be cases where there is something that is required here or let's say you know there was a different min sdk version required that wasn't already satisfied by capacitor what we could do to set up this preference manually is actually just add this to our capacitor.config.json file so what we can do is open up capacitor.config.json which should be in the root directory of your project and under the cordover section we can add a preferences object and then you can just add whatever preference that you want to set so if we were setting android min sdk version we could set that to 15 and that would then be copied over into our native project when we run npx cap sync again so just to see that happening let's save that and let's again take a quick look at our android studio project so we see it's just that uh one entry there for now but if we jump back into here run mpx cap sync and then if we jump back into our android studio project you'll see that pops in there so now we have that preference in there as well uh if we needed it i'm actually going to get rid of that because it's not required in this case but i think it's important to show how to do that if you need to do it and another important thing to point out i think is that you can see here that this config.xml file has ended up in res xml config.xml which is exactly the target that is specified here but this is just uh i guess a coincidence or the way this is set up uh capacitor will only ever add config.xml entries to this one file uh if this target was something else like uh res forward slash xml forward slash some plugin forward slash config.xml it would still get added into this same file anyway the target here doesn't actually matter it only matters that it has config.xml in its name another important point that we will get to in just a little bit is that aside from looking for config.xml it also or capacitor also has a different behavior for entries here that have a target that includes android manifest.xml as well but we'll talk about that in a second okay so moving on to the next section here we have source file and source android facebook connect.xml and a target directory of res forward slash values so what could a cordova is trying to do here is create this facebook connect.xml file and then in this next section it is trying to set some values inside of that file so it creates it and then we target that file and add some configuration to it but we just discussed how it will only capacitor will only copy over values if there is config.xml in the target file and it will copy those into this file that we've been working with here so since this is facebookconnect.xml it's actually just going to get ignored so this whole section basically is like nothing happened at least in capacitors view it will however create this file still so if we go into let me just close this capacitor cordova android plugins and go to source main res values we will see that there is a facebook connect.xml file that is created but there's nothing inside of it it's just an empty resources tag so what we want is to have all of these values that the plugin is going to use we want to have those in this file but we don't so this is where those cordova install variables come in it wants to replace this app id app name facebook hybrid app events it wants to replace those with the values supplied when installing the plugin and then add them to the project which would then make these available to use throughout the android project so generally if some value some string or boolean or whatever kind of variable is trying to be set up by the plugin there's a good chance it's doing that for a reason and it's going to want to make use of that value so this is something that we're going to need to set up ourselves usually so we're not going to add the values directly to this file what we can do is just go to our main application up here open up source main res values and in here we can store any uh variables we want to use throughout the application so we can set up our strings and booleans in here so basically we can just look at what uh the facebook plugin was trying to do here so it's trying to set up this fb app id fb app name and fb underscore hybrid underscore app underscore events so we can just set those up ourselves in this file so i'm just going to paste those in now so i'll save that and now the plugin is going to be able to make use of those values another good thing to do not specifically required but if we open up that connect uh native file again was it connect plug-in so if we open that up what you can do is just search for those values in this code so i might search for fb underscore app id to see how that belly is actually being made use of so in the case of the facebook plugin here it's not actually making use of any of these variables within the native code here so technically we don't need to add these it's just later in the config that is making use of these but sometimes these values will be referenced throughout the actual native code so it's generally best to get these set up properly in the application okay so let's move on to the next section which is the androidmanifest.xml file here so you can see this is another config file tag here and as i mentioned before any config files that don't have config.xml in its target name will be ignored by a capacitor except for ones that have a target of androidmanifest.xml so these are values that the plugin wants to add to the manifest file and these uh capacitor actually does handle automatically for us basically what will happen here is it will copy it into the androidmanifest.xml file that is within the capacitor cordova android plugins folder so if we open that up we can see that we have these exact values here activity and two we have right here which has been added automatically and you can see that it's also making use of those strings that we created so it's going to pull those values in from this file and when this application is built it will take this android manifest.xml that's going to get combined with any other android manifest.xml files in the project to create the final manifest okay so let's move on to the next tag here which is this framework tag and it has a source of com.facebook android facebook android sdk and then it wants to add the facebook android sdk version here so what this will do basically is capacitor will see this and add it to the capacitor.build.gradle file as a dependency so if we open up this file here we can see that this is automatically been added for us under dependencies we have implementation and then the value that was supplied in the plugin.xml file and so you'll notice here that it has a value of 5.13.0 which might seem a bit magical because we never actually supplied that value so what will happen is a capacitor will look to see if a preference is set for facebook android sdk version and in this plugin.xml file at the top here there is a preference supplied for that version number and so it's just going to use the default value that's supplied but if you didn't want to use that default version it is also possible to overwrite this value and you can't do it in this file because as you can see at the top of this file it says do not edit this file because it's generated every time that a sync is run so any changes you make in here is going to get wiped out but what you can do is open up the android folder here and open the variables.gradle file and if you set the version as a variable in here it will use that value instead so if i add a new line here and say facebook android sdk version and let's just create a just a random version number let's say 5.9.0 for example that's that's the version we want to use so we'll save that and now let's run uh the mpx cap sync which is the same as uh update in terms of the native project a sync will just run both the update and copy commands at the same time so i'll run mpx cap sync and we'll wait for that to finish and now if we jump back into the android studio project and you can see we have this implementation line here still but this time we have facebook android sdk version left as just a placeholder a variable here and what will happen is this uh will be replaced with whatever values are in the variables.gradle file and so you can see here since we have facebook android sdk version that is going to use that value uh there instead so that leaves us with just one more uh line to look at here for the android platform and that's another source file uh entry here and so this is just it trying to create the connect plugin.java file so in terms of cordova the cordova plugin itself it's saying where to grab that file from the plugin project and where we want to put it and as we saw before when we were just clicking around we can see that that file is indeed copied inside of org.apache.cordover.facebook which is what it's trying to specify there and then we have our connectplugin.java file which is providing all of the native code for this plugin so in the end for this plugin there was actually very little we needed to manually set up mostly it was just setting up these variables which in a lot of cases is probably all you will need to do but if you follow along this process there may be some cases where there is additional things you need to configure and this is going to make that hopefully pretty clear because you'll see what cordova is trying to do and what capacitor isn't adding to the native project and then you can just do it yourself in a lot of cases that will probably work but there may be cases where the plugin just isn't compatible okay so i hope you found this video useful uh if you did like it do feel free to leave a like and subscribe and i will see you in the next video [Music] you

Channel: Joshua Morony

Views: 3,408

Keywords: ionic, ionic4, ionic 4, tutorial, tutorials, ionic tutorials, ionic framework, coding, coding tutorials, angular, angular tutorials, cordova, cordova tutorials, capacitor tutorials, mobile, mobile apps, apps, html5, ios, android, native, hybrid, pwa, web apps, progressive web applications, programming, software

Id: Q3WH7kvEdkA

Length: 26min 19sec (1579 seconds)

Published: Tue Sep 08 2020