Newton
public final class Newton : NSObject
Newton iOS SDK v2.3.0 Copyright © 2018 Buongiorno S.p.A. All rights reserved.
-
Get the SDK version represented as a String composed of TAG + GIT-SHORT-HASH + DATE of compile
Declaration
Swift
public static let versionString: String
-
Get the SDK Build number as an Integer
Declaration
Swift
public static let buildNumber: Int
-
Get the actual enviroment the SDK is running on. Can be PROD-SANBOX or PROD-RELEASE
Declaration
Swift
public var environmentString: String { get }
-
Used to initialize Newton for the first time It must be placed soon at the beginning of Application initialization Recommended: place the call to this method in UIApplication’s application(_:didFinishLaunchingWithOptions:) method
Throws
throws NWError.NewtonInitializationError when called two times, NWError.NewtonNotInitialized when there were problems in initialization
Declaration
Swift
public class func getSharedInstanceWithConfig(conf: String, customData: NWSimpleObject? = nil) throws -> Newton
Parameters
conf
a String representing the secret
customData
a NWSimpleObject to add custom data in Session Start event
Return Value
the Newton singleton
-
Subsequent calls to obtain Newton singleton NOTE: Initialize Newton before asking for singleton
Throws
throws NWError.NewtonNotInitialized when the singleton is not initialized. Call getSharedInstanceWithConfig first
Declaration
Swift
public class func getSharedInstance() throws -> Newton
Return Value
the Newton singleton
-
Obtain the Login Builder object serves as a builder of one or more Login Flow via a build call
building is always possible provided that all the parameters which a Login Flow should know, are provided before the build call is done
it can be provided a parameter via a set call
when a partcular Login flow is built, if one or more parameters are missing the build throw an exception
If a build is successful you can create even more copies of the same login flow, and everyone of them will be ready to be started, even if the builder object dies and is recycled from the memory
before building it checks if user isn’t already logged or if there aren’t any current running Login Flow at the moment
Declaration
Swift
public func getLoginBuilder() -> NWLoginBuilder
Return Value
the NWLoginBuilder object
-
Obtain the list of available OAUTH providers it can be used when building an NWOAuthLoginFlow to pass the correct name of the provider via the setOAuthProvider
- login flow interested: OAUTH
Declaration
Swift
public func getOAuthProviders() -> [String]
Return Value
an array of Strings of the provider supported
-
Dummy Method only for Frameworks alignments
Declaration
Swift
public func finalizeLoginFlow()
-
Obtain the Identity Builder object this is the object needed to perform all the actions regarding identity when a user has correctly logged in IdentityBuilder can add a new identity, delete just one, obtain the list.
Declaration
Swift
public func getIdentityBuilder() -> NWIdentityBuilder
Return Value
the NWIdentityBuilder object
-
Getting the actual User credential It can be one of the following, ordered by priority:
- The Newton Token [EXPIRABLE] which is the one obtained after a login flow
- The Autologin Token [EXPIRABLE] the credential obtained to perform automatic flow internally
- The Anonymous token [NOT EXPIRABLE] calculated on a device basis, and which is unique for the device and application
Declaration
Swift
public func getUserToken() -> String
Return Value
the String reperesenting the actual User Token possessed
-
Ask if an User is logged inside Newton
Warning
This is a
best effort
answer, meaning that the SDK won’t sync with the backend to check if the credential is expired To be sure that the answer is aligned with Newton backend please use syncUserState(callback:)Declaration
Swift
public func isUserLogged() -> Bool
Return Value
a Bool if the user is logged in or not
-
Obtain the User Meta Info related to a completed login flow It gives information about which login flow completed succesfully (in case many were built), if the user is new (signup or login), other meta information such as the Facebook token (in case of a Facebook OAuth login)
Warning
This information expires, so it’s important to ask it shortly after a login process has been doneDeclaration
Swift
public func getUserMetaInfo(callback: @escaping MetaInfoCallback)
Parameters
callback
the MetaInfoCallback invoked when the meta info are available
-
Explicit logout of a user These are the steps of logging out:
- If user is not logged it does nothing
- It deletes all the credentials (tokens, meta info) possessed
- The stateChangeListener callback is invoked to inform the user has log out
- A Logout Analytic Event is fired
Declaration
Swift
public func userLogout()
-
Sets a callback to be informed whenever the user state changes from logged to unlogged and vice versa
Warning
There can be only one listener (should be global inside an application). Subsequent calls to this method will override the previuos oneDeclaration
Swift
public func setOnUserStateChangeListener(listener: UserStateChangeListener)
Parameters
listener
the UserStateChangeListener
-
Synchronizing with Newton backend to refresh the User Token possessed Use this method to be assured that the information about User (like isUserLogged) are fresh
Declaration
Swift
public func syncUserState(callback: @escaping SyncStateCallback)
Parameters
callback
SyncStateCallback invoked without error if the synchronization was made correctly
-
Deletion of a user (deprecated) It produces:
- the delete on the Newton Backend of a specific user logged with a Login Flow
- if the global stateChangeListener is set it is invoked
- an analytic event of Logout is sent
Warning
The user must be logged in with Any Login Flow except from CustomDeclaration
Swift
public func __temporaryUserDelete(callback: @escaping UserDeleteCallback)
Parameters
callback
invoked when the delete has been performed
-
Push Notification Module Obtain the NWPushManager object, wich handles the APNS registration and the push notification receiving procedures
Throws
NWError.PushNotificationError if push notification are not supported
Declaration
Swift
public func getPushManager() throws -> NWPushManager
Return Value
the NWPushManager object
-
Payment Manager Module Obtain the NWPaymentManager object, wich handles the in app payment procedures
Declaration
Swift
public func getPaymentManager() throws -> NWPaymentManager
Return Value
the NWPaymentManager object
-
Retrieve Session Identifier
Throws
NWError.NewtonNotInitialized in case singleton not initialized correctlyDeclaration
Swift
public func getSessionId() -> String
Return Value
the actual session identifier
-
Generate a token referring the actual User that can be used from all other applications in the realm
Note
the user can be even Anonymous. Of course the application using this token will not retrieve any User
Throws
NewtonNotInitialized error
Declaration
Swift
public func generateTransientToken(callback: @escaping GenerateTransientTokenCallback) throws
Parameters
callback
the callback with the async response
-
Send a Custom Event
Important
Custom Event is sent, along with its name and custom data, to communicate an immediate action which is interesting for the application.
Throws
EventCreationError if constraints are not passed NewtonNotInitialized if Singleton is not correctly initialized Serialization on disk error can be thrown too
Declaration
Swift
func sendEvent(name: String, customData: NWSimpleObject? = nil) throws
Parameters
name
the identification of the event. Constraint regex ^[\w-]{1,32}$
customData
a SimpleObject that stores key/value pairs useful to attach more information to the event. Please see SimpleObject for constraints
-
Start a Timed Event
Important
An event that represent something that has been started in the application and that finishes after some time. For this kind of event the name identifies uniquely the timer name: in fact you cannot start the same timer two times, or try to stop a timer never started. The timers live with the life of the application, so if application is stopped they are descructed too.
Throws
EventCreationError if constraints are not passed, InvalidEvent if a timer with the same name is already started, NewtonNotInitialized if Singleton is not correctly initialized, Serialization on disk error can be thrown too
Declaration
Swift
func timedEventStart(name: String, customData: NWSimpleObject? = nil) throws
Parameters
name
the name of the timer to be started. Constraint regex ^[\w-]{1,32}$
customData
a SimpleObject that stores key/value pairs useful to attach more information to the event. Please see SimpleObject for constraints
-
Stop a Timed Event
Important
An event that represent something that has been started in the application and that finishes after some time. For this kind of event the name identifies uniquely the timer name: in fact you cannot start the same timer two times, or try to stop a timer never started. The timers live with the life of the application, so if application is stopped they are descructed too.
Throws
EventCreationError if constraints are not passed, InvalidEvent if the timer doesn’t exist, NewtonNotInitialized if Singleton is not correctly initialized, Serialization on disk error can be thrown too
Declaration
Swift
func timedEventStop(name: String, customData: NWSimpleObject? = nil) throws
Parameters
name
the name of the timer to be stopped. Constraint regex ^[\w-]{1,32}$
customData
a SimpleObject that stores key/value pairs useful to attach more information to the event. Please see SimpleObject for constraints
-
Begin an Analytic Flow Begin the flow once the action has started. The name can help in understanding the kind of flow
Important
A flow is an aggregation of events that starts at a certain time, have some evolution steps, and then finish with three types of ending: success, failure or canceled. This event persists among sessions and so there can only be one at a time.
Warning
Starting again a flow will end with failure the previous one
Throws
EventCreationError if constraints are not passed, NewtonNotInitialized if Singleton is not correctly initialized, Serialization on disk error can be thrown too
Declaration
Swift
func flowBegin(name: String, customData: NWSimpleObject? = nil) throws
Parameters
name
the name of the flow. Constraint regex ^[\w-]{1,32}$
customData
a SimpleObject that stores key/value pairs useful to attach more information to the event. Please see SimpleObject for constraints
-
Step iteration of an Analytic Flow There can be zero to many step, each one with its name. The name can help in understanding the kind of step
Important
A flow is an aggregation of events that starts at a certain time, have some evolution steps, and then finish with three types of ending: success, failure or canceled. This event persists among sessions and so there can only be one at a time.
Throws
EventCreationError if constraints are not passed, InvalidEvent if flow is not begun, NewtonNotInitialized if Singleton is not correctly initialized, Serialization on disk error can be thrown too
Declaration
Swift
func flowStep(name: String, customData: NWSimpleObject? = nil) throws
Parameters
name
the name of the step. Constraint regex ^[\w-]{1,32}$
customData
a SimpleObject that stores key/value pairs useful to attach more information to the event. Please see SimpleObject for constraints
-
Ending with success an Analytic Flow End with success a flow when it has been accomplished succesfully
Important
A flow is an aggregation of events that starts at a certain time, have some evolution steps, and then finish with three types of ending: success, failure or canceled. This event persists among sessions and so there can only be one at a time.
Throws
EventCreationError if constraints are not passed, InvalidEvent if flow is not begun, NewtonNotInitialized if Singleton is not correctly initialized, Serialization on disk error can be thrown too
Declaration
Swift
func flowSucceed(reason: String = "ok", customData: NWSimpleObject? = nil) throws
Parameters
name
The optional reason of ending (default
ok
). Constraint regex ^[\w-]{1,32}$customData
a SimpleObject that stores key/value pairs useful to attach more information to the event. Please see SimpleObject for constraints
-
Ending with success an Analytic Flow End with failure a flow when something went wrong that cannot be recovered
Important
A flow is an aggregation of events that starts at a certain time, have some evolution steps, and then finish with three types of ending: success, failure or canceled. This event persists among sessions and so there can only be one at a time.
Throws
EventCreationError if constraints are not passed, InvalidEvent if flow is not begun, NewtonNotInitialized if Singleton is not correctly initialized, Serialization on disk error can be thrown too
Declaration
Swift
func flowFail(reason: String, customData: NWSimpleObject? = nil) throws
Parameters
name
The reason of failure. Constraint regex ^[\w-]{1,32}$
customData
a SimpleObject that stores key/value pairs useful to attach more information to the event. Please see SimpleObject for constraints
-
End by user cancel of an Analytic Flow End with cancel only when the user explicitly aborts the whole process
imporant: A flow is an aggregation of events that starts at a certain time, have some evolution steps, and then finish with three types of ending: success, failure or canceled. This event persists among sessions and so there can only be one at a time.
Throws
EventCreationError if constraints are not passed, InvalidEvent if flow is not begun, NewtonNotInitialized if Singleton is not correctly initialized, Serialization on disk error can be thrown too
Declaration
Swift
func flowCancel(reason: String, customData: NWSimpleObject? = nil) throws
Parameters
name
The optional reason of abort. Constraint regex ^[\w-]{1,32}$
customData
a SimpleObject that stores key/value pairs useful to attach more information to the event. Please see SimpleObject for constraints
-
Check if a specific timer is currently running
Declaration
Swift
func isTimedEventRunning(name: String) -> Bool
Parameters
name
the name of the timer
Return Value
a Bool indicating if the specific timer is running
-
Check if Analytic flow is in progress
Declaration
Swift
func isAnalyticFlowBegun() -> Bool
Return Value
a Bool indicating if the flow has begun but not ended yet
-
Get the current analytic name
Warning
the name of the actual analytic flow is returned, so this can be an intermediate step as well as a flow begunThrows
EventAnalyticError if there is no Analytic Flow in progress
Declaration
Swift
func getCurrentAnalyticFlowName() throws -> String
Return Value
the String of the actual analytic flow
-
Rank a Content over a specfic Scope
Important
This is about recommendation in an application. It leverages the analytics channel to identify relevant actions over a content (identified by content id) inside a category (scope) and with a numeric weight (multiplier). It’s all at discretion of the product
Throws
EventCreationError if constraints are not passed,
Declaration
Swift
func rankContent(contentId: String, scope: RankingScope, multiplier: Float = 1.0) throws
Parameters
contentId
The content identifier
scope
The RankingScope
multiplier
A Float to modify the weight of the rank
-
Attach the current session to a master one
Throws
EventCreationError if constraints are not passed,
Declaration
Swift
func attachMasterSession(masterSessionId: String, masterUserId: String, customData: NWSimpleObject? = nil) throws
Parameters
masterSessionId
The master session identifier
masterUserId
The master user id logged
customData
a SimpleObject that stores key/value pairs useful to attach more information to the event. Please see SimpleObject for constraints
-
Rank a Content over a specfic Scope
Important
This is about recommendation in an application. It leverages the analytics channel to identify relevant actions over a content (identified by content id) inside a category (scope) and with a numeric weight (multiplier). It’s all at discretion of the product
Throws
EventCreationError if constraints are not passed,
Declaration
Swift
func attachSession(attachedSessionId: String, attachedUserId: String?, attachType: AttachType, customData: NWSimpleObject? = nil) throws
-
Dummy Method only for Frameworks alignments
Declaration
Swift
func flushEvents(flushCallback callback: NWCallback)
Parameters
callback
a callback