Skip to content

Latest commit

 

History

History
220 lines (175 loc) · 7.95 KB

README.md

File metadata and controls

220 lines (175 loc) · 7.95 KB
Raw

Piano SDK for iOS

Piano SDK includes dynamic frameworks written in Swift.

Version Platform License

  • PianoOAuth: component for authentication with user providers Piano ID and Piano Accounts. Frameworks can be used for development iOS applications on Objective-c and Swift.

Version Platform License

This document details the process of integrating the Piano SDK with your iOS application. If you have any questions, don't hesitate to email us at [email protected].

Requirements

  • iOS 9.0+
  • Xcode 12.0
  • Swift 5.1

Installation

CocoaPods

Add the following lines to your Podfile.

use_frameworks!

pod 'PianoComposer', '~>2.3.12'
pod 'PianoOAuth', '~>2.3.12'

Then run pod install. For details of the installation and usage of CocoaPods, visit official web site.

PianoComposer Usage

Imports
// swift
import PianoComposer
// objective-c
@import PianoComposer;
Endpoints
PianoEndpoint.production // Production endpoint
PianoEndpoint.productionAustralia // Production endpoint for Australia region
PianoEndpoint.productionAsiaPacific // Production endpoint for Asia/Pacific region
PianoEndpoint.sandbox // Sandbox endpoint
Initialize
PianoComposer(aid: "<PUBLISHER_AID>") // Production endpoint is used by default (PianoEndpoint.production)
// or
PianoComposer(aid: "<PUBLISHER_AID>", endpoint: PianoEndpoint.sandbox)
Usage
var composer = PianoComposer(aid: "<PUBLISHER_AID>")
.delegate(self) // conform PianoComposerDelegate protocol
.tag("tag1") // add single tag
.tag("tag2") // add single tag
.tags(["tag3", "tag4"]) //add array of tags
.zoneId("Zone1") // set zone
.referrer("http://sitename.com") // set referrer
.url("http://pubsite.com/page1") // set url
.customVariable(name: "customId", value: "1") // set custom variable
.userToken("userToken") // set user token
Composer execution
composer.execute()
PianoComposerDelegate protocol
// Client actions
optional func composerExecutionCompleted(composer: PianoComposer)

// Composer actions from server 
optional func showLogin(composer: PianoComposer, event: XpEvent, params: ShowLoginEventParams?)
optional func showTemplate(composer: PianoComposer, event: XpEvent, params: ShowTemplateEventParams?)
optional func nonSite(composer: PianoComposer, event: XpEvent)
optional func userSegmentTrue(composer: PianoComposer, event: XpEvent)
optional func userSegmentFalse(composer: PianoComposer, event: XpEvent)    
optional func meterActive(composer: PianoComposer, event: XpEvent, params: PageViewMeterEventParams?)
optional func meterExpired(composer: PianoComposer, event: XpEvent, params: PageViewMeterEventParams?)    
optional func experienceExecute(composer: PianoComposer, event: XpEvent, params: ExperienceExecuteEventParams?)
Show templates

We recommend to use that tag in mobile templates for correct display on iOS devices

<meta name="viewport" content="width=device-width, initial-scale=1">

PianoOAuth Usage

Imports

// swift
import PianoOAuth
// objective-c
@import PianoOAuth;

Piano accounts user provider

Usage
let vc = PianoOAuthPopupViewController(aid: "<PUBLISHER_AID>") // for piano accounts user provider
...
vc.delegate = someDelegate // conform PianoOAuthDelegate protocol
vc.signUpEnabled = true // makes "sign up" button enabled (default: false)
vc.widgetType = .login // widget type (possible values: ".login", ".register")
vc.showPopup()
PianoOAuthDelegate protocol
func loginSucceeded(accessToken: String)
func loginCancelled()
Screenshots

iPhone example

iPad example

Piano ID user provider

Piano ID

PianoID requires a custom URL Scheme to be added to your project. To add: open your project configuration select your app from the TARGETS section, then select the Info tab, and expand the URL Types section.

Set io.piano.id.<PUBLISHER_AID_LOWERCASE> as URL schemes. For example: Url scheme example

To enable social sign in, you must configure the PianoID shared instance before usage.

PianoID.shared.aid = "<PUBLISHER_AID>"
PianoID.shared.delegate = self

Also you must implement the application(_:open:options:) method of your app delegate

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    return PianoOAuth.PianoIDApplicationDelegate.shared.application(app, open: url, options: options)
}

For iOS 8 and older you must implement the deprecated application(_:open:sourceApplication:annotation:) method of your app delegate

func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool {
    return PianoOAuth.PianoIDApplicationDelegate.shared.application(application, open: url, sourceApplication: sourceApplication, annotation: annotation)
}

To sign in:

PianoID.shared.signIn()

To sign out:

PianoID.shared.signOut(token: "<TOKEN>")

Additional settings:

PianoID.shared.isSandbox = true // for using sandbox application
PianoID.shared.widgetType = .login // or .register for choosing default screen 
PianoID.shared.signUpEnabled = false // for enabling/disabling signUp
Native Google Sign In SDK

You must implement the application(_:didFinishLaunchingWithOptions:) method of your app delegate

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    PianoID.shared.googleClientId = "<PUBLISHER_GOOGLE_CLIENT_ID>"    
    return true
}

Information about <PUBLISHER_GOOGLE_CLIENT_ID> can be found here: https://developers.google.com/identity/sign-in/ios/start-integrating#get_an_oauth_client_id

Also you should configure URL scheme as described here: https://developers.google.com/identity/sign-in/ios/start-integrating#add_a_url_scheme_to_your_project

Native Facebook Sign In SDK

You must implement the application(_:didFinishLaunchingWithOptions:) method of your app delegate

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {    
    PianoOAuth.PianoIDApplicationDelegate.shared.application(application, didFinishLaunchingWithOptions: launchOptions)
    return true
}

Also you should configure your application as described here: https://developers.facebook.com/docs/swift/register-your-app#configuresettings

Passwordless Login in SDK

These settings should be configured in Piano ID according to https://docs.piano.io/enabling-passwordless-checkout/. The current configuration is applied in mobile application without additional settings

PianoIDDelegate protocol
func pianoID(_ pianoID: PianoID, didSignInForToken token: PianoIDToken!, withError error: Error!)
func pianoID(_ pianoID: PianoID, didSignOutWithError error: Error!)
pianoIDSignInDidCancel(_ pianoID: PianoID)