Development

The easiest way to have your iOS app open links in Puffin Browser is to use URL schemes. The following examples will show you how to use Puffin Browser as an external component.

Puffin Browser supports URL Schemes

Puffin Browser for iOS handles the following URL Schemes.

  • puffin for http
  • puffins for https
  • puffin-x-callback for callbacks back to calling app (iOS after version 3.5)

You can use the following code to check if these URL schemes are available. But note that it can not be determined whether Puffin Browser or Puffin Free Browser will be opened.

	[[UIApplication sharedApplication] canOpenURL:
		[NSURL URLWithString:@"puffin://"]];

To actually open a URL in Puffin Browser, the URL scheme provided in the URL must be changed from http/https to puffin/puffins. The following sample code opens a URL in Puffin Browser:

	NSURL *inputURL = [NSURL URLWithString:@"http://www.puffinbrowser.com"];
	NSString *scheme = inputURL.scheme;

	// Replace the URL Scheme
	NSString *toScheme = nil;
	if ([scheme isEqualToString:@"http"]) {
		toScheme = @"puffin";
	} else if ([scheme isEqualToString:@"https"]) {
		toScheme = @"puffins";
	}

	// Proceed only if a valid URL Scheme is available.
	if (toScheme) {
		NSString *urlString = [inputURL absoluteString];
		NSRange rangeForScheme = [urlString rangeOfString:@":"];
		NSString *urlNoScheme = [urlString substringFromIndex:rangeForScheme.location];
		NSString *result = [toScheme stringByAppendingString:urlNoScheme];
		NSURL *URL = [NSURL URLWithString:result];

		// Open it on Puffin Browser
		[[UIApplication sharedApplication] openURL:URL];
	}

If Puffin Brorwser is installed, it will invoke Puffin with the URL provided and replace the scheme as needed.

Support x-callback

Puffin Browser for iOS also supports x-callback after version 3.5. x-callback is an open specification for inter-app communication and messaging between iOS apps that provide a way for other apps to open Puffin Browser and specify a callback URL to return to the calling app. Applications have to register a URL scheme which will be used to return back to itself after opening the URL on Puffin Browser.


The URL scheme is:

  • puffin-x-callback

The scheme will accept x-callback-url compliant URLs with the "open" action and the following parameters:
  • url: (required) the URL to open; must be encoded
  • x-success: (optional) the URL to call when the user completes operation on Puffin.
  • x-source: (optional) the name shown on Puffin "back to app" button

For example:

	NSString *unescaped = @"http://www.puffinbrowser.com";
	NSString *escapedString = (NSString *)CFURLCreateStringByAddingPercentEscapes(
		NULL,
		(CFStringRef)unescaped,
		NULL,
		CFSTR("!*'();:@&=+$,/?%#[]\" "),
		kCFStringEncodingUTF8);
	NSString *prefix = @"puffin-x-callback://x-callback-url/open/?url=";
	NSString *URLString = [prefix stringByAppendingString:escapedString];
	NSURL *URL = [NSURL URLWithString:URLString];

	// only open given url without any callback
	[[UIApplication sharedApplication] openURL:URL];

Use a callback with x-success

The calling app can specify a URL as a callback when user complete navigation on Puffin Browser by using x-success parameter in the x-callback-url. The app can specify x-source parameter which will be used to show app name on Puffin back to button. The app needs to register its own URL scheme in order for Puffin to return to it. If the app does not provide x-source, Puffin Browser will show "Back to APP" by default.


For example:

	NSString *URLString = @"puffin-x-callback://x-callback-url/open/?url=http%3A%2F%2Fwww.puffinbrowser.com&x-success=myapp%3A%2F%2f&x-source=myAPP";
	NSURL *URL = [NSURL URLWithString:URLString];

	[[UIApplication sharedApplication] openURL:URL];

Please contact info@cloudmosa.com for any development issues