kaldor/piano-composer-only-ios

Please don't use this fork which simply disables everything we didn't need, use upstream

Piano SDK for iOS

Piano SDK includes dynamic frameworks written in Swift.

• PianoCommon: common components for the SDK

• PianoComposer: provides access to the mobile composer (Apple TV support)

• PianoTemplate: template components

• PianoTemplate.ID: template components for Piano ID

• 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.

• PianoC1X: component for integration Piano Composer with Cxense.

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 support@piano.io.

Requirements

• iOS 12.0+
• Xcode 14.0
• Swift 5.7

Installation

CocoaPods

Add the following lines to your Podfile.

use_frameworks!

pod 'PianoComposer', '~> 2.6.1'
pod 'PianoTemplate', '~> 2.6.1'
pod 'PianoTemplate.ID', '~> 2.6.1'
pod 'PianoOAuth', '~> 2.6.1'
pod 'PianoC1X', '~> 2.6.1'

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

Swift Package Manager

Add the components you need from the repository:

URL: https://gitlab.com/piano-public/sdk/ios/package

Version: 2.6.1

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 showForm(composer: PianoComposer, event: XpEvent, params: ShowFormEventParams?)
optional func showRecommendations(composer: PianoComposer, event: XpEvent, params: ShowRecommendationsEventParams?)
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?)

Templates

For more information about templates, see the documentation at the link.

PianoOAuth Usage

Imports

// swift
import PianoOAuth

// objective-c
@import PianoOAuth;

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:

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 SceneDelegate(iOS 13+) implement scene(_,openURLContexts) method:

class SceneDelegate: UIResponder, UIWindowSceneDelegate {

    ...

    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        guard let url = URLContexts.first?.url else {
            return
        }

        _ = PianoIDApplicationDelegate.shared.application(
            UIApplication.shared,
            open: url,
            sourceApplication: nil,
            annotation: [UIApplication.OpenURLOptionsKey.annotation]
        )
    }
}

For SwiftUI (iOS 14+) you must implement the onOpenURL(perform) method of your ContentView

@available(iOS 14.0, *)
struct MyApp: App {
    
    ...
    
    var body: some Scene {
        WindowGroup {
            ContentView().onOpenURL { url in
                PianoIDApplicationDelegate.shared.application(UIApplication.shared, open: url, sourceApplication: nil, annotation: nil)
            }
        }
    }
}

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 signIn(result: PianoIDSignInResult!, withError error: Error!);

func signOut(withError error: Error!);

func cancel();

User information

To get user information, use the function PianoID.userInfo

PianoID.shared.userInfo(aid: "<YOUR_AID>", accessToken: "<USER_ACCESS_TOKEN>", formName: "<FORM_NAME>") { result, err in
    if let e = err {
        // handle error
        return
    }
    
    // handle user information result
}

For update user information, use the function PianoID.putUserInfo

putUserInfo(
    aid: "<AID>",
    accessToken: "<USER_ACCESS_TOKEN>",
    formName: "<FORM_NAME>",
    customFields: [
        "<FIELD_NAME>": "<FIELD_VALUE>"
    ]
) { result, error in
    if let error {
        // handle error
        return
    }
    
    // handle updated user information result
}

Cxense integration

For more information about Cxense integration (C1X), see the documentation at the link.