swiftkitz / appz

📱 Launch external apps, and deeplink, with ease using Swift!

Appz 📱

Deeplinking to external applications made easy

Highlights

• Web Fallback Support:
  In case the app can't open the external application, it will fall-back to a web URL that is guaranteed to succeed by opening the browser.

• Isolated App Specs:
  It was crucial to make sure the library can scale as the number of supported apps increase. Therefor, each supported app is implemented in isolation in a separate file.

• Full Autocomplete Support: The API has been carefully designed to make the most out of auto complete features, so you don't even have to peak into any docs or code!

• Full Testing:
  To make the specs as transparent as possible, the library has tests to make sure every external application action has tests with the expected results.

Features

You can try them in the playground shipped with the framework!

Concise syntax to trigger deep linking:

let app = UIApplication.shared
app.canOpen(Applications.Instagram())
app.open(Applications.AppStore(), action: .account(id: "395107918"))
app.open(Applications.AppSettings(), action: .open)

Transparent web fallback:

// In case the user doesn't have twitter installed, it will fallback to
// https://twitter.com/testUser/statuses/2
app.open(Applications.Twitter(), action: .status(id: "2",  screenName: "testUser"))

Add your applications:

// Applications are recommended to be part of the
// "Applications" namespace
extension Applications {
    // Define your application as a type that
    // conforms to "ExternalApplication"
    struct MyApp: ExternalApplication {

        typealias ActionType = Applications.MyApp.Action

        let scheme = "myapp:"
        let fallbackURL = ""
        let appStoreId = ""
    }
}
// Then, you define the actions your app supports
extension Applications.MyApp {

    enum Action: ExternalApplicationAction {

        case open

        // Each action should provide an app path and web path to be
        // added to the associated URL
        var paths: ActionPaths {

            switch self {
            case .open:
                return ActionPaths()
            }
        }
    }
}

app.open(Applications.MyApp(), action: .open)

Supported Apps (for now!):

App	Actions
AirLaunch	Open
AliExpress	Open
AllCast	Open
AppleMaps	Open
AppSettings	Open
AppStore	Developer, App, Rate App
AppleWatch	Open
Audible	Open
Ayah	Open
Behance	Open, UserProfile
BNR	Open
Box	Open
Buzzfeed	Open
Calendars5	Open
Camera360	Open
Careem	Open
Chromecast	Open
CirclePay	Open, Request, Send
Clips	Open
Cnet	Open
CNN	Open
Currency	Open
DailyMotion	Open
DamaKing	Open
DayCost	Open
DayOne	Open
Diigo	Open
Documents	Open
Dropbox	Open
Duolingo	Open
eBay	Open
Echofon	Open
Epson	Open
Everypost	Open
EyeEm	Open
Facebook	Open, Profile, Notification, Feed, Page, Action
FaceTime	Video Call
FaceTime audio	Audio Call
Feedly	Open
FileApp	Open
FindFriends	Open
FindiPhone	Open
Fitbit	Open
Flickr	Open
Flipboard	Open
FlippsTV	Open
Forest	Open
Foursquare	Open
FriendlySocial	Open
Gallery	Open
Glympse	Open
GoogleCalendar	Open, CreateEvent
GoogleChrome	Open
GoogleDocs	Open
GoogleDrive	Open
GoogleEarth	Open
GoogleMail	Open
GoogleMaps	Open, Display Directions, Display Location, Search
GooglePhotos	Open
GooglePlus	Open
GoogleSheets	Open
GoogleSlides	Open
GoogleTranslate	Open
GroupeMe	Open
Heapo	Open
HootSuite	Open
iBooks	Open
IMDb	Open, Search, Title, Boxoffice, Showtimes, Feature Coming Soon, Feature Best Picture, Feature Born Today, Top rated movies, Most popular movies.
iMovie	Open
INRIXTraffic	Open
Instagram	Open, Camera, Library, Media, Username, Location, Tag
Instapaper	Open
iShows	Open
iTranslate	Open, Translate
iTunesU	Open
KakaoTalk	Open
Kayak	Open
Keeper	Open
Kik	Open
LastPass	Open
Line	Open
Linkedin	Open
Mail	Compose
Marktplaats	Open
Marvis	Open
Meerkat	Open
Messages	SMS
MobileMouse	Open
Mopico	Open
Moves	Open
Music	Open
MyFitnessPal	Open
NameShark	Open
Netflix	Open
Notes	Open
NPORadio	Open
NU.nl	Open
NYTimes	Open
OneMorething	Open
OneDrive	Open
OnePassword	Open
Outlook	Open, Compose
Paypal	Open
Periscope	Open
Phone	Open
Photos	Open
PicCollage	Open
Pinterest	Open, UserProfile, Search
Pocket	Open
Podcasts	Open
Quora	Open
Radium	Open
RemindersApp	Open
Remote	Open
Rijnmond	Open
RoboForm	Open
RunKeeper	Open
ScannerPro	Open
Simplenote	Open
Skitch	Open
Skype	Open
Slack	Open, Channel, Direct Message, Open File, Search
Snapchat	Open, Add
Snapseed	Open
Songpop2	Open
Sonos	Open
Soundflake	Open
Spark	Compose
StitcherRadio	Open
Strava	Open
SubwayKorea	Open
SunriseCalendar	Open
Swarm	Open
Super-Stickman-Golf-2	Open
Talabat	Open
Tango	Open
Ted	Open
Telegram	Open, SMS, openFromID
TestFlight	Open
Tinder	Open
Trello	Open
Tubex	Open
Tumblr	Open, Dashboard, Explore, Activity, Blog, Tag
Tweetbot	Timeline, Post, Mentions, Lists, Retweets, Favorites, Messages, Status, Search, Profile, Follow, Unfollow, Favorite, Unfavorite, Retweet, List
Twitter	Status, UserHandle, UserId, List, Post, Search, Timeline, Mentions, Messages
Twitterrific	Open, MentionsView, MessagesView, FavoritesView, Search, TweetID, MessageID, Post, UserProfile
Uber	Open
Unread	Open
Ustream	Open
Viber	Open Calls Tab, Open Chats Tab
Videos	Open
Views	Open
Vimeo	Open
Vine	Open, Popular Timelines
VIPAccess	Open
Vox	Open
Voxer	Open
VSCO	Open
Wallet	Open
Waze	Open, NavigateToDirection
WeChat	Open
Weibo	Open
WhatsApp	Open
Whyd	Open
Wikipanion	Open
WordPress	Open
Workflow	Open
Yammer	Open
Yelp	Open, Search, Search Location, Search Category, Search Category Location, Business
Youtube	Open, Open Video
FRIL	Open

Getting Started

Configure Info.plist

You must add the schemes you want to use to your app's info.plist file under LSApplicationQueriesSchemes. See here for more.

Carthage

Carthage is fully supported. Simply add the following line to your Cartfile:

github "SwiftKitz/Appz"

Cocoapods

Cocoapods is fully supported. Simply add the following line to your Podfile:

pod 'Appz'

Submodule

For manual installation, you can grab the source directly or through git submodules, then simply:

• Drop the Appz.xcodeproj file as a subproject (make sure Copy resources is not enabled)
• Navigate to your root project settings. Under "Embedded Binaries", click the "+" button and select the Appz.framework

Motivation

I've gone through way too much pain than I am willing to admit integrating deeplinking in my app. It is very easy to forget calling canOpenURL or missing a colon somewhere. Another pain point was savaging the web for all the different specs for different applications.

With this library, you can keep the external application deep linking spec separately and rest assured as it is open source and maintained by the wonderful github community!

Author

Mazyod (@Mazyod)

Contributors

This library could not have made it so far without the generous contributions of various developers!

License

Appz is released under the MIT license. See LICENSE for details.

appz's Issues

Swinject

Hi,

What about integrating Swinject with Appz ?

Example project

Should we create an example project for the library?

Design Header

Need this repo to be a bit attractive!

Consider simplifying ExternalApp structure

Having added applications inherit ExternalApplication gives us a lot of flexibility, but I am starting to question the need for such a flexible design. Perhaps making it a simple struct instance would reduce all the boilerplate code written for the added apps... Need to investigate.

FourSquare error

Hello! Thanks for the framework. I use it to open the FourSquare app, but I get the error -canOpenURL: failed for URL: "foursquare:" - error: "I could add foursquare to Info. Plist. Please tell me how can I fix this?

Carthage Support

🍖 or something

missing argument label in call (have actions, expected options)

installed via cocoaPods
project is Swift 3

Support URLs without a hostname

Some URLs seems to be missing a hostname, something like:

let url = "scheme:key=value"

We should accommodate such format, probably by tweaking the ExternalApplication protocol through adding some properties to indicate such format.

Support for native clock app

Streamline the process of adding new apps

Instead of manually writing new Swift classes, tests, pod specs, and modifying the readme, we can have a configuration file with all the apps specs we have, and then a script that generates all the files needed. This will help us move much faster and adapt to future changes more quickly.

Tasks

• Design the configuration files
• Script the Swift source files generator
• Script the Pod Subspecs generator
• Script the readme table generator

Trigger opening in Docs@Work

Hello,

Not sure how exactly this library works (not an iOS developer), but is it possible to trigger opening of an arbitrary document like docx/xlsx/pdf (from an URL location) inside an external office app e.g. MobileIron's Docs@Work? Is it enough to write another swift file and somehow embed this into my own app?

My app deals with documents and the security is handled by MobileIron. MobileIron is a type of EMM and what they do is they wrap IPA files into a secure containers and, on the other side, also provide a sort of Office app called Docs@Work which is used to open all these formats in read-only mode (no copy-paste, sharing etc).

Can I trigger document opening from my app using your Appz library?

Many thanks,
Baki

Explore Platform Support

Start with tvOS, then watchOS, and maybe Mac OS.

Update the pod version

Could be cool to update the pod version with le latest PRs and updates :)

Thank you for this library 👍

More actions to Strava app

Hello,

I found Strava API v3

I think it will help us in adding more actions to Strava app. I will be glad to add more actions, but I don't have a Strava account to test the new actions.

P.S. I can create a Strava account, but I think it will be useless because I will not have activities, followers, ..

Thanks.

Allow opening the AppStore to download a missing app

It would be great to add a capability for developers to redirect users to the AppStore in order to download a specific app, in case it is missing. This feature doesn't work for all applications, since some applications have web interfaces we can use instead, without downloading the app.

The feature should be designed such that the developer would willingly opt-in to opening the AppStore for downloading the specific app if it is missing, and doesn't just happen transparently.

Google Drive opens Safari only

I'm calling this and it gets me to Safari tab, instead of app, that's installed a it was opened before.

UIApplication.shared.open(Applications.GoogleDrive(), action: .open)

This code gets me to the Google Maps app.

UIApplication.shared.open(Applications.GoogleMaps(), action: .open)

QueryParam's order

I know this is really stupid, but some apps, do not support QueryParameters like they should, and only support QueryItems in custom order. (like Maps.Me)

Any suggestions on how to fix this problem?
I was trying to add:

enum Query {
    case parameters([String:String])
    case items([URLQueryItem])

    var queryItems: [URLQueryItem] {
        switch self {
            case .parameters(let params): return params.map { URLQueryItem(name: $0, value: $1) }
            case .items(let queryItems): return queryItems
        }
    }
}

And use Query as an input, But since Path's queryParameters is variable and public, it'll definitely break backward compatibility.
Any suggestions?

LSApplicationQueriesSchemes in plist

i was testing the library on a dummy app im working on, and found that i need to add the apps uri scheme in the info.plist file in iOS 9 primarily
is there is a way to avoid that or even add our own plist file in the library with all the shemes so that developers using this library use it as a reference?

Two apps not installed with pod install

Salaam,

I discovered a weird issue! when I run pod install everything installed except the two apps, I added yesterday. I'm sure I added them to all targets: iOS, tvos, and watchOS. And the most weird part is when I downloaded Appz as zip file I found these two apps: NYTimes, and Skitch. Any suggestion?

Just the needed app

Salaam,

I'm thinking of a way to give the developer the ability to just install the app he/she need. Because maybe the developer just need one or few apps so no need to install 155 apps, Do you agree with me?

I think we can offer this feature but I don't know how but I'm thinking, searching, and sharing thoughts so we will solve it إن شاء الله

Hmm, I think the best way is to combine all apps with just open action together (one class), and then use enum or .. to decide which scheme, baseURL, and paths to use. Do you agree? this will reduce file number to more than half.

Maybe my thinking is wrong but I think we have to reduce file number ..

Complete Test Coverage

This library heavily relies on tests for correctness, so this is crucial.

API for checking if App is available

After seeing #9, it is apparent that the developer will need to ask if the app is available or not. Something like:

if AvailableApps.Twitter.installed {
    // Twitter is installed
}

A suggestion: supported platform versions

Hey,

I found this 👇🏼

I would I like to add it to all SwiftKitz repos. It's fine ?

Can you please provide me with all the supported platform versions ? or could you please guide me to an easy way to find the supported platform versions ?

Thanks.

URL parameters

I don't think the current escape method used properly escapes URL query parameters, since it doesn't encode &. This means if the user passes & as a value, it will mess up the URL query.

Instagram query parameters

Hey great work,

But in the Instagram.swift file the query parameters for the enum .Username should be "username" and not "id"

tweetbot support

i have found this on tweetbot official site link it works on both tweetbot 3 and 4, even if we don't specify a screen name it would work too.
The issue is if i requested favourites and the favourites tab is hidden in the app it self then the favourites tab wouldn't show instead it would just open the app.
So should i implement it anyway, and if yes what should be the fall back url?

Settings System ?

Hello , it's possible to go on my Settings system with this plugin ?
For example , in my app , i check if my wifi is activate, if my wifi is not activate , i want to go on Settings system (Android or Ios) to activate wifi .
It's possible ?

Cocoapods support

Spread the ☕ ❤️

swift 2.3, swift 3

Hello!
Do you have any plans on migrating library to newer versions of swift?

Update docs and playground

Thanks to #6, we have mail and SMS support. We should update the readme and playground with those.

URL scheme for Google Calendar

Hi @Dreamersoul,
thanks for this great project!
I want to ask, is there a way to pass the event detail info to Google Calendar by the scheme? I've searched for a long time but no useful result was found. (Google Maps provide one : https://developers.google.com/maps/documentation/urls/ios-urlscheme , but not good for the calendar).
I try my luck here, any advise will be appreciated.
Thanks again.

Investigate MS Apps

MS apps seem to have an issue when being launched, need to investigate further.. See #28

Google Maps

Hello,

Regarding this

Should we add comgooglemaps-x-callback?

Add links for the apps website

We should link the apps in the readme file to publisher website, for easy referencing.

Add support for iOS 10 async operation

iOS 10 adds a way to asynchronously try opening an applications, and registering a callback once that's over:

open func open(_ url: URL, options: [String : Any] = [:], completionHandler completion: (@escaping (Bool) -> Swift.Void)? = nil)

We can probably provide a new method that conditionally compiles if the minimum SDK requirement is iOS 10.

About versioning

I have noticed that the version of this library is still at v1.0.0, Should we increment it in the readme file and the podespec or what?

Makes sense to add Firefox

https://github.com/mozilla/firefox-ios-open-in-client