var h=Object.defineProperty,c=Object.defineProperties;var u=Object.getOwnPropertyDescriptors;var r=Object.getOwnPropertySymbols;var o=Object.prototype.hasOwnProperty,d=Object.prototype.propertyIsEnumerable;var l=(t,n,a)=>n in t?h(t,n,{enumerable:!0,configurable:!0,writable:!0,value:a}):t[n]=a,e=(t,n)=>{for(var a in n||(n={}))o.call(n,a)&&l(t,a,n[a]);if(r)for(var a of r(n))d.call(n,a)&&l(t,a,n[a]);return t},s=(t,n)=>c(t,u(n));var p=(t,n)=>{var a={};for(var i in t)o.call(t,i)&&n.indexOf(i)<0&&(a[i]=t[i]);if(t!=null&&r)for(var i of r(t))n.indexOf(i)<0&&d.call(t,i)&&(a[i]=t[i]);return a};const layoutProps={},MDXLayout="wrapper";function MDXContent(a){var i=a,{components:t}=i,n=p(i,["components"]);return mdx(MDXLayout,s(e(e({},layoutProps),n),{components:t,mdxType:"MDXLayout"}),mdx("p",null,"The best place to initialise the ",mdx("inlineCode",{parentName:"p"},"SDK")," is in your ",mdx("inlineCode",{parentName:"p"},"Application")," class. If you don't have it, you can create one by extending the ",mdx("inlineCode",{parentName:"p"},"android.app.Application")," class. If you need to check whether the SDK is initialised for the app business logic, check if the flag ",mdx("inlineCode",{parentName:"p"},"ZettleSDK.isInitialized")," is set to ",mdx("inlineCode",{parentName:"p"},"true"),"."),mdx("p",null,"After initialisation, you need to start the SDK. Preferably, this is done by adding an observer on behalf of the SDK, to the ",mdx("inlineCode",{parentName:"p"},"ProcessLifecycleOwner"),". This way the SDK will automatically start and stop itself."),mdx("p",null,"You can also handle it manually by calling ",mdx("inlineCode",{parentName:"p"},"start()")," and ",mdx("inlineCode",{parentName:"p"},"stop()"),"."),mdx("pre",null,mdx("code",e({parentName:"pre"},{className:"language-kotlin"}),`class MyApplication : Application() { fun onCreate() { val clientId = getString(R.string.client_id) val scheme = getString(R.string.redirect_url_scheme) val host = getString(R.string.redirect_url_host) val redirectUrl = "$scheme://$host" val config = config(applicationContext) { isDevMode = devMode auth { this.clientId = clientId this.redirectUrl = redirectUrl // For Managed Authentication this.tokenProvider = tokenProvider // New in SDK v2 (For Provided Authentication) } addFeature(CardReaderFeature.Configuration) addFeature(PayPalQrcFeature.Configuration) addFeature(VenmoQrcFeature.Configuration) addFeature(ManualCardEntryFeature.Configuration) } val sdk = ZettleSDK.configure(config) // Attach the SDKs lifecycle observer to your lifecycle. It allows the SDK to // manage bluetooth connection in a more graceful way ProcessLifecycleOwner.get().lifecycle.addObserver(ZettleSDKLifecycle()) // Alternatively, start the SDK manually, but remember to also stop it manually through sdk.stop() or ZettleSDK.instance?.stop() sdk.start() } // ... } `)),mdx("h2",e({},{id:"user-authentication"}),"User authentication"),mdx("p",null,"An important addition in the SDK v2 is the ability to provide your own authentication solution, and provide the SDK the required tokens only."),mdx("p",null,"Hence, as an integrator, you have a bigger responsibility since the SDK will no longer try to log in the user automatically. Instead, whenever the SDK needs access to a scope, you will have to provide the tokens."),mdx("p",null,"The difference also lies in the SDK's initialization (configuration) call, where you decide your desired authentication approach."),mdx("ul",null,mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Managed Authentication")," - the one that has been used before where the SDK handles all UI. "),mdx("li",{parentName:"ul"},mdx("strong",{parentName:"li"},"Provided Authentication")," - the new option for SDK v2 where you as the integrator handles retrieving and providing the tokens to the SDK.")),mdx("h4",e({},{id:"the-difference-in-setup"}),"The difference in setup"),mdx("table",null,mdx("thead",{parentName:"table"},mdx("tr",{parentName:"thead"},mdx("th",e({parentName:"tr"},{align:"center"})),mdx("th",e({parentName:"tr"},{align:"center"}),mdx("strong",{parentName:"th"},"Managed Authentication")),mdx("th",e({parentName:"tr"},{align:"center"}),mdx("strong",{parentName:"th"},"Provided Authentication")))),mdx("tbody",{parentName:"table"},mdx("tr",{parentName:"tbody"},mdx("td",e({parentName:"tr"},{align:"center"}),mdx("strong",{parentName:"td"},"Installation")),mdx("td",e({parentName:"tr"},{align:"center"}),"Need to include the ",mdx("inlineCode",{parentName:"td"},"redirect_url")," in ",mdx("inlineCode",{parentName:"td"},"AndroidManifest")),mdx("td",e({parentName:"tr"},{align:"center"}),"No need to include the ",mdx("inlineCode",{parentName:"td"},"redirect_url")," in ",mdx("inlineCode",{parentName:"td"},"AndroidManifest"),", because the ",mdx("inlineCode",{parentName:"td"},"OAuthActivity")," is not used and the SDK won't adhere to callbacks from web views.")),mdx("tr",{parentName:"tbody"},mdx("td",e({parentName:"tr"},{align:"center"}),mdx("strong",{parentName:"td"},"Configuration")),mdx("td",e({parentName:"tr"},{align:"center"}),"Need to provide the ",mdx("inlineCode",{parentName:"td"},"clientId")," and ",mdx("inlineCode",{parentName:"td"},"redirectUrl")," matching the ones declared in the ",mdx("inlineCode",{parentName:"td"},"AndroidManifest")),mdx("td",e({parentName:"tr"},{align:"center"}),"Need to provide the ",mdx("inlineCode",{parentName:"td"},"clientId")," and ",mdx("inlineCode",{parentName:"td"},"tokenProvider")," which implement one of the ",mdx("inlineCode",{parentName:"td"},"TokenProvider")," interfaces")),mdx("tr",{parentName:"tbody"},mdx("td",e({parentName:"tr"},{align:"center"}),mdx("strong",{parentName:"td"},"Authentication")),mdx("td",e({parentName:"tr"},{align:"center"}),"Call the ",mdx("inlineCode",{parentName:"td"},"login")," function from your Activity"),mdx("td",e({parentName:"tr"},{align:"center"}),"The ",mdx("inlineCode",{parentName:"td"},"provideTokens")," function of the ",mdx("inlineCode",{parentName:"td"},"TokenProvider")," interface will be called when needed.")))),mdx("h5",e({},{id:"installation"}),"Installation"),mdx("p",null,"To configure the SDK to use managed authentication, the manifest must include the redirect-url described in the ",mdx("a",e({parentName:"p"},{href:"https://developer.zettle.com/docs/android-sdk/installation-and-configuration#authentication"}),"Installation and Configuration under section Authentication"),"."),mdx("p",null,"But when you use provided authentication, there's no need for the manifest to include the redirect-url . The OAuthActivity is not used and the SDK won't adhere to callbacks from web views."),mdx("h5",e({},{id:"configuration"}),"Configuration"),mdx("p",null,"The second difference is when we create the configuration object for the SDK. Then, for the managed authentication, we need to provide the ",mdx("inlineCode",{parentName:"p"},"clientId")," and ",mdx("inlineCode",{parentName:"p"},"redirectUrl")," matching the ones declared in the ",mdx("inlineCode",{parentName:"p"},"AndroidManifest")," as in example below:"),mdx("pre",null,mdx("code",e({parentName:"pre"},{}),`auth { this.clientId = clientId this.redirectUrl = redirectUrl } `)),mdx("p",null,"But since we don't need the redirect url in provided authentication, the configuration and the SDK need a token provider instead, as shown in the following code snippet. Additionally, the token provider needs to implement one of the TokenProvider interfaces described later. "),mdx("pre",null,mdx("code",e({parentName:"pre"},{}),`auth { this.clientId = clientId this.tokenProvider = tokenProvider } `)),mdx("h3",e({},{id:"initiate-managed-authentication"}),"Initiate Managed Authentication"),mdx("p",null,"To authenticate a user, call the ",mdx("inlineCode",{parentName:"p"},"login")," method from your Activity, and provide a toolbar color compatible with your color theme."),mdx("pre",null,mdx("code",e({parentName:"pre"},{className:"language-kotlin"}),`private fun doProvidedUILogin() { ZettleSDK.instance?.login(this, ResourcesCompat.getColor(resources, R.color.colorAccent, null)) } `)),mdx("h5",e({},{id:"initiate-managed-authorisation-with-refresh-token"}),"Initiate Managed Authorisation with refresh token"),mdx("p",null,"You can also authorise the user with a refresh-token to omit the initial UI and callback to log in a user if you already possess a valid refresh-token. However, since this is managed authentication, if the token needs to acquire new scopes or the token is invalidated and can't be refreshed, the SDK UI will prompt the user to log in."),mdx("p",null,`The SDK requires a proof key for code exchange (PKCE) flow to authorise the user. If you have a PKCE flow setup to get access and refresh tokens, you can call the `,mdx("inlineCode",{parentName:"p"},"login")," method with the refresh token as a parameter. For information on how to set up a PKCE flow, see ",mdx("a",e({parentName:"p"},{href:"/docs/api/oauth/user-guides/set-up-app-authorisation/set-up-authorisation-code-grant-with-pkce"}),"OAuth PKCE method"),"."),mdx("pre",null,mdx("code",e({parentName:"pre"},{className:"language-kotlin"}),`private fun doTokenLogin() { ZettleSDK.instance?.login("pre-authorized-refresh-token") } `)),mdx("blockquote",null,mdx("p",{parentName:"blockquote"},mdx("strong",{parentName:"p"},"Note:")," You still need to declare the ",mdx("inlineCode",{parentName:"p"},"OAuthActivity")," in your manifest since it's used for performing refunds.")),mdx("h3",e({},{id:"initiate-provided-authentication"}),"Initiate Provided Authentication"),mdx("p",null,"To opt in and use the provided authentication, you first need to implement one of the available ",mdx("inlineCode",{parentName:"p"},"TokenProvider")," interfaces. This could be either the ",mdx("inlineCode",{parentName:"p"},"TokenProviderAsync")," for a callback manner, or ",mdx("inlineCode",{parentName:"p"},"TokenProviderSuspending")," to utilize Coroutines. They both have only one function named ",mdx("inlineCode",{parentName:"p"},"provideTokens"),"."),mdx("p",null,"The ",mdx("inlineCode",{parentName:"p"},"provideTokens")," function will be called with the scopes needed, and as an integrator, it is up to you to provide proper ",mdx("inlineCode",{parentName:"p"},"accessToken")," and possibly ",mdx("inlineCode",{parentName:"p"},"refreshToken")," for those scopes. When a refresh token is provided, the SDK will persist it and try to refresh the tokens automatically."),mdx("pre",null,mdx("code",e({parentName:"pre"},{className:"language-kotlin"}),`typealias TokenProviderCallback = (OAuthTokens) -> Unit sealed interface TokenProvider interface TokenProviderAsync : TokenProvider { fun provideTokens(scopes: Array, callback: TokenProviderCallback) } interface TokenProviderSuspending : TokenProvider { suspend fun provideTokens(scopes: Array): OAuthTokens } `)),mdx("p",null,"Send your implementation to one of the above interfaces in the ",mdx("inlineCode",{parentName:"p"},"auth")," configuration to the SDK at startup. "),mdx("blockquote",null,mdx("p",{parentName:"blockquote"},mdx("strong",{parentName:"p"},"Note:")," In your provider, we strongly recommend that you don't change the thread or dispatcher."),mdx("p",{parentName:"blockquote"},mdx("strong",{parentName:"p"},"Note:")," If you are using your own provider, you no longer need to accommodate the built-in handling in the ",mdx("inlineCode",{parentName:"p"},"AndroidManifest.xml")," file which means you can remove the ",mdx("inlineCode",{parentName:"p"},"com.izettle.android.auth.OAuthActivity"),", and as you can see from the auth configuration, you no longer need to provide a redirect URL. It will never be used by the SDK.")),mdx("p",null,"Zettle SDK considers the refund scope as more sensitive than the others. Hence, for an authenticated user, the access token and the refresh token do not include the refund scope. Therefore, the SDK must request the provider for tokens that include refund scope by calling ",mdx("inlineCode",{parentName:"p"},"provideTokens"),"."),mdx("p",null,"In this scenario, if the SDK is given only an access token without a refresh token, it will store the previously authenticated refreshable tokens in its memory. However, it will use the newly fetched, more sensitive token while it remains valid, before falling back to the stored tokens."),mdx("p",null,"If a token is returned without a refresh token, it will be kept as a temporary token until it expires. After this, the SDK will try to use the previously stored refresh token again. But whenever a token is returned with a refresh token, this will take the place of the primary token, and all temporary tokens will be forgotten."),mdx("p",null,"Refer to the diagram below to see the flow when the SDK needs access tokens."),mdx("pre",null,mdx("code",e({parentName:"pre"},{className:"language-mermaid"}),`flowchart LR A[Need access] --> B{has valid
accessToken?} B -->|Yes| C{has
required
scopes?} B -->|No| D{has valid
refreshToken?} D -->|No| X D -->|Yes| E{Refreshing
successful?} E -->|Yes| C E -->|No| X C -->|Yes| Y C -->|No| X X --> Y Y[Continue] X[Ask provider
for tokens] `)),mdx("p",null,'To prevent infinite loops of retrieving tokens from the provider, the SDK trusts that the provided tokens are correct and attempts to use them. If the tokens are invalid, it will result in an "unauthorized" error.'),mdx("p",null,"As an integrator, you can have complete control of the access tokens and authorisation flow by never providing the refresh-tokens to the SDK. In this case, the SDK will then only keep the access token for its short lifespan and always request new tokens on expiration since it doesn't have any refresh token to use."),mdx("h3",e({},{id:"observe-auth-state"}),"Observe auth state"),mdx("p",null,"To check if the user is logged in or not, you can do the following:"),mdx("ul",null,mdx("li",{parentName:"ul"},"Read a simple flag indicating whether a user is logged in or not.")),mdx("pre",null,mdx("code",e({parentName:"pre"},{className:"language-kotlin"}),`when(ZettleSDK.instance?.isLoggedIn) { true -> // user is logged in else -> // need to authenticate a user } `)),mdx("ul",null,mdx("li",{parentName:"ul"},"Observe the authentication state live data ",mdx("inlineCode",{parentName:"li"},"authState"),".")),mdx("pre",null,mdx("code",e({parentName:"pre"},{className:"language-kotlin"}),`private val authObserver = Observer { when (it) { is User.AuthState.LoggedIn -> // User authenticated is User.AuthState.LoggedOut -> // There is no authenticated user } } override fun onCreate(savedInstanceState: Bundle?) { // ... ZettleSDK.instance?.authState?.observe(this, authObserver) //... } `)),mdx("p",null,"The ",mdx("inlineCode",{parentName:"p"},"User.AuthState.LoggedIn")," instance has an ",mdx("inlineCode",{parentName:"p"},"info")," property with the following fields."),mdx("table",null,mdx("thead",{parentName:"table"},mdx("tr",{parentName:"thead"},mdx("th",e({parentName:"tr"},{align:"left"}),"Name"),mdx("th",e({parentName:"tr"},{align:"left"}),"Type"),mdx("th",e({parentName:"tr"},{align:"left"}),"Description"))),mdx("tbody",{parentName:"table"},mdx("tr",{parentName:"tbody"},mdx("td",e({parentName:"tr"},{align:"left"}),mdx("inlineCode",{parentName:"td"},"publicName")),mdx("td",e({parentName:"tr"},{align:"left"}),mdx("inlineCode",{parentName:"td"},"String?")),mdx("td",e({parentName:"tr"},{align:"left"}),"Public company or merchant name.")),mdx("tr",{parentName:"tbody"},mdx("td",e({parentName:"tr"},{align:"left"}),mdx("inlineCode",{parentName:"td"},"imageUrl")),mdx("td",e({parentName:"tr"},{align:"left"}),mdx("inlineCode",{parentName:"td"},"ProfileImageUrl?")),mdx("td",e({parentName:"tr"},{align:"left"}),"Profile image in small, medium and large size.")),mdx("tr",{parentName:"tbody"},mdx("td",e({parentName:"tr"},{align:"left"}),mdx("inlineCode",{parentName:"td"},"userId")),mdx("td",e({parentName:"tr"},{align:"left"}),mdx("inlineCode",{parentName:"td"},"String?")),mdx("td",e({parentName:"tr"},{align:"left"}),"Unique user ID.")),mdx("tr",{parentName:"tbody"},mdx("td",e({parentName:"tr"},{align:"left"}),mdx("inlineCode",{parentName:"td"},"organizationId")),mdx("td",e({parentName:"tr"},{align:"left"}),mdx("inlineCode",{parentName:"td"},"String?")),mdx("td",e({parentName:"tr"},{align:"left"}),"Unique organisation ID")),mdx("tr",{parentName:"tbody"},mdx("td",e({parentName:"tr"},{align:"left"}),mdx("inlineCode",{parentName:"td"},"timeZone")),mdx("td",e({parentName:"tr"},{align:"left"}),mdx("inlineCode",{parentName:"td"},"TimeZoneId")),mdx("td",e({parentName:"tr"},{align:"left"}),"Merchant time zone.")),mdx("tr",{parentName:"tbody"},mdx("td",e({parentName:"tr"},{align:"left"}),mdx("inlineCode",{parentName:"td"},"country")),mdx("td",e({parentName:"tr"},{align:"left"}),mdx("inlineCode",{parentName:"td"},"CountryId?")),mdx("td",e({parentName:"tr"},{align:"left"}),"Merchant country.")),mdx("tr",{parentName:"tbody"},mdx("td",e({parentName:"tr"},{align:"left"}),mdx("inlineCode",{parentName:"td"},"currency")),mdx("td",e({parentName:"tr"},{align:"left"}),mdx("inlineCode",{parentName:"td"},"CurrencyId")),mdx("td",e({parentName:"tr"},{align:"left"}),"Currency used for all payments and refunds.")))),mdx("h2",e({},{id:"related-tasks"}),"Related tasks"),mdx("ul",null,mdx("li",{parentName:"ul"},mdx("a",e({parentName:"li"},{href:"/docs/android-sdk/installation-and-configuration"}),"Installation and configuration")),mdx("li",{parentName:"ul"},mdx("a",e({parentName:"li"},{href:"/docs/android-sdk/user-guides/manage-card-payments"}),"Manage card payments")),mdx("li",{parentName:"ul"},mdx("a",e({parentName:"li"},{href:"/docs/android-sdk/user-guides/manage-paypal-qrc-payments"}),"Manage PayPal QRC payments")),mdx("li",{parentName:"ul"},mdx("a",e({parentName:"li"},{href:"/docs/android-sdk/user-guides/manage-manual-card-entry-payments"}),"Manage PayPal QRC payments")),mdx("li",{parentName:"ul"},mdx("a",e({parentName:"li"},{href:"/docs/android-sdk/user-guides/manage-in-app-pairing"}),"Manage in-app pairing")),mdx("li",{parentName:"ul"},mdx("a",e({parentName:"li"},{href:"/docs/android-sdk/user-guides/manage-extra-amount-tipping-flow"}),"Manage extra amount tipping flow")),mdx("li",{parentName:"ul"},mdx("a",e({parentName:"li"},{href:"/docs/android-sdk/user-guides/manage-total-amount-tipping-flow"}),"Manage total amount tipping flow"))))}MDXContent.isMDXComponent=!0;