DeepLink Kit
Overview
DeepLink Kit is a splendid route-matching, block-based way to handle your deep links. Rather than decide how to format your URLs, parse them, pass data, and navigate to specific content or perform actions, this library and a few lines of code will get you on your way.
Full Documentation
Guide to add Universal Links to your app
Check it out
Try the DeepLinkKit
sample project by running the following command:
pod try "DeepLinkKit"
Installation
CocoaPods
DeepLinkKit is available through CocoaPods. To install
the library, simply add the following line to your Podfile:
pod "DeepLinkKit"
Carthage
To install via Carthage, add the following line to your Cartfile
:
github "button/DeepLinkKit"
Other
If you don't use CocoaPods or Carthage, you can include all of the source files from the DeepLinkKit directory in your project.
Usage
Add deep link support to your app in 5 minutes or less following these simple steps.
Note: As of 1.0.0
, all imports should be updated to import <DeepLinkKit/DeepLinkKit.h>
.
1. Make sure you have a URL scheme registered for your app in your Info.plist
![](https://cloud.githubusercontent.com/assets/1057077/5710380/8d913f3e-9a6f-11e4-83a2-49f6564d7a8f.png)
2. Import DeepLinkKit
#import <DeepLinkKit/DeepLinkKit.h>
3. Create an instance of DPLDeepLinkRouter
in your app delegate
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
self.router = [[DPLDeepLinkRouter alloc] init];
return YES;
}
4. Register a route handler
Objective-C
self.router[@"/log/:message"] = ^(DPLDeepLink *link) {
NSLog(@"%@", link.routeParameters[@"message"]);
};
Swift
self.router.register("/log/:message") { link in
if let link = link {
print("\(link.routeParameters["message"])")
}
}
5. Pass incoming URLs to the router
- (BOOL)application:(UIApplication *)application
openURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication
annotation:(id)annotation {
return [self.router handleURL:url withCompletion:NULL];
}
6. Passing NSUserActivity
objects to the router (optional)
Note: If your application supports Apple's new universal links, implement the following in your app delegate:
- (BOOL)application:(UIApplication *)application
continueUserActivity:(NSUserActivity *)userActivity
restorationHandler:(void (^)(NSArray *))restorationHandler {
return [self.router handleUserActivity:userActivity withCompletion:NULL];
}
Learn more about the DeepLinkKit by reading our Integration Guide.
Route Registration Examples
URLs coming into your app will be in a similar format to the following:
<scheme>://<host>/<path-component>/<path-component>
When registering routes, it's important to note that the first forward slash in your registered route determines the start of the path to be matched. A route component before the first forward slash will be considered to be the host.
Say you have an incoming URL of twitter://timeline
router[@"timeline"] = ^{ … }
router[@"/timeline"] = ^{ … }
In another example, a URL of twitter://dpl.com/timeline
router[@"/timeline"] = ^{ … }
router[@"timeline"] = ^{ … }
You can also be scheme specific. If you support multiple URL schemes in your app, you can register routes specific to those schemes as follows:
An incoming URL of scheme-one://timeline
router[@"scheme-one://timeline"] = ^{ … }
router[@"scheme-two://timeline"] = ^{ … }
Regex Route Matching
You can use regex in your route patterns as well to give you maximum flexibility.
Match any url
The following will match all incoming urls
router[@".*"] ^(DPLDeepLink *link){
}
Note: Routes are matched in the order they're registered so registering this route first will prevent all other more specific routes from matching.
Match any url with a given scheme
The following will match all incoming links with the scheme, myscheme://
router[@"myscheme://.*"] ^(DPLDeepLink *link){
}
You can name your regex groups too
The following will match any url with a host
of trycaviar.com
and hand you :path
in the route params.
router[@"trycaviar.com/:path(.*)"] ^(DPLDeepLink *link){
}
Match multiple path components
In this example, you'll get :city
and :restaurant
in the route params.
router[@"trycaviar.com/:city([a-zA-Z]+)/:restaurant(.*)"] ^(DPLDeepLink *link){
}
If the restaurant ids are numbers, you could limit your matches as follows.
router[@"trycaviar.com/:city([a-zA-Z]+)/:restaurant([0-9])"] ^(DPLDeepLink *link){
}
Name some groups and not others
router[@"trycaviar.com/:city([a-zA-Z]+)/[a-z]+/:restaurant(.*)"] ^(DPLDeepLink *link){
}
The above would match ‘https://trycaviar.com/manhattan/pizza/nicoletta-297’ but not ‘https://trycaviar.com/manhattan/PIZZA/nicoletta-297’ or ‘https://trycaviar.com/manhattan/pizza-places/nicoletta-297’, etc
AppLinks Support
Does your app support AppLinks? You can easily handle incoming AppLinks by importing the AppLinks category DPLDeepLink+AppLinks
. The AppLinks category provides convenience accessors to all AppLinks 1.0 properties.
router[@"/timeline"] = ^(DPLDeepLink *link) {
NSURL *referrerURL = link.referralURL;
NSString *someValue = link.extras[@"some-key"];
}
Running the Demo
To run the example project, run pod try DeepLinkKit
in your terminal. You can also clone the repo, and run pod install
from the project root. If you don't have CocoaPods, begin by follow this guide.
There are two demo apps, SenderDemo
, and ReceiverDemo
. ReceiverDemo
has some registered routes that will handle specific deep links. SenderDemo
has a couple actions that will deep link out to ReceiverDemo
for fulfillment.
Run theSenderDemo
build scheme first, then stop the simulator and switch the build scheme to ReceiverDemo
and run again. Now you can switch back to the SenderDemo
app in the simulator and tap on one of the actions.
Creating Deep Links
You can also create deep links with DPLMutableDeepLink
. Between two DeepLinkKit
integrated apps, you can pass complex objects via deep link from one app to another app and easily get that object back on the other end.
In the first app:
DPLMutableDeepLink *link = [[DPLMutableDeepLink alloc] initWithString:@"app-two://categories"];
link[@"brew-types"] = @[@"Ale", @"Lager", @"Stout", @"Wheat"]
link[@"beers"] = @{
@"ales": @[
@{
@"name": @"Southern Tier Pumking Ale",
@"price": @799
},
@{
@"name": @"Sierra Nevada Celebration Ale",
@"price": @799
}
],
@"lagers": @[
...
],
...
}
[[UIApplication sharedApplication] openURL:link.URL];
In the second app:
router[@"categories"] = ^(DPLDeepLink *link) {
NSArray *brewTypes = link[@"brew-types"];
NSDictionary *beers = link[@"beers"];
}
Authors
Wes Smith
Chris Maddern
License
DeepLinkKit is available under the MIT license. See the LICENSE file for more info.
Contributing
We'd love to see your ideas for improving this library. The best way to contribute is by submitting a pull request. We'll do our best to respond to you as soon as possible. You can also submit a new Github issue if you find bugs or have questions. :octocat:
Please make sure to follow our general coding style and add test coverage for new features!