This project is the iOS library component of the MobileDeepLinking specification, the industry standard for mobile application deeplinking. This specification and accompanying libraries simplify and reduce implementation time for deep links as well as provide flexible and powerful features for routing to custom behavior.
Given a configuration file (MobileDeepLinkingConfig.json), this library provides an app the ability to route incoming deeplinks to view controllers or custom logic. It has the ability to automatically instantiate and push view controllers onto the navigation controller, as well the ability to register callback handlers that are executed when matching a deeplink.
When a view is defined in the configuration file, the library will instantiate the viewController as appropriate and then attempt to push it to the appropriate navigation controller. The route parameters defined in the configuration file (path and query parameters) will be set on this viewController.
Three types of viewControllers are supported. They are listed below with the appropriate json configuration settings:
- Storyboard - requires
storyboard(storyboard name) andidentifier(view storyboard identifier) attributes - Xib - requires
identifier(xib name) andclass(viewController class name) attributes. - Non Interface Builder View Controller - requires
class(viewController class name) attribute.
There may be cases where you need to set up a view before displaying it. This functionality is supported through the use of custom handlers. In the didFinishLaunchingWithOptions method in your AppDelegate, you can register blocks (essentially callback functions) that will be executed when an associated route is matched. This association takes place in the configuration json.
These handlers are provided with an NSDictionary with all route parameters found in the deeplink. They can modify the contents of this dictionary, which will be forwarded on to the next handler in the handlers array. Handlers can be reused across multiple routes and can be used in conjunction with view instantiation or entirely on their own.
This library was developed using ARC and supports iOS 5 and above on all architectures.
This library follows the iOS Framework build process laid out here. The library can be found in the releases/ folder. It is also available through CocoaPods.
To build from source:
- Build the
MobileDeepLinking-iOSscheme. - Build the
Frameworkscheme. - Expand the
Productsfolder in Xcode, right click the .a file, and click "Show in Finder". Within this folder you will see your.frameworkfolder. This is the built framework file that can be dropped into other projects.
Create a MobileDeepLinkingConfig.json file in your project with your desired routes and options. See demo app and spec for examples.
Insert the following line into the - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation method in your AppDelegate:
[[MobileDeepLinking sharedInstance] routeUsingUrl:url];
Register Custom Handlers (if desired) in your AppDelegate's didFinishLaunchingWithOptions method:
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
[[MobileDeepLinking sharedInstance] registerHandlerWithName:@"exampleHandler" handler:^void(NSDictionary *params)
{
NSLog(@"exampleHandler");
}];
}
This assumes you have CocoaPods installed.
- Run
pod install - Open
MobileDeepLinking.xcworkspace - Test using 'MobileDeepLinking-iOS' scheme.
Part of the MobileDeepLinking.xcworkspace includes MobileDeepLinkingDemo. This is a demo application that provides an example implementation of the MobileDeepLinkingConfig.json file, along with several custom handlers that demonstrate how to route to client-specified functionality. It also provides example routing to a storyboard based view, a xib based view, and a view without any Interface Builder elements.
Copyright 2014 MobileDeepLinking.org and other contributors http://mobiledeeplinking.org
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:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.