Newton

public final class Newton: NSObject

Newton iOS SDK v1.2.0 Copyright © 2015 d-MobileLab 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 = (VCS_TAG ?? "") + " " + VCS_SHORT_HASH + " " + VCS_DATE
  • Get the SDK Build number as an Integer

    Declaration

    Swift

    public static let buildNumber = VCS_NUM
  • Get the actual enviroment the SDK is running on. Can be PROD-SANBOX or PROD-RELEASE

    Declaration

    Swift

    public var environmentString: String
  • 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()
  • Getting the actual User credential It can be one of the following, ordered by priority:

    1. The Newton Token [EXPIRABLE] which is the one obtained after a login flow
    2. The Autologin Token [EXPIRABLE] the credential obtained to perform automatic flow internally
    3. 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 done

    Declaration

    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:

    1. If user is not logged it does nothing
    2. It deletes all the credentials (tokens, meta info) possessed
    3. The stateChangeListener callback is invoked to inform the user has log out
    4. 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 one

    Declaration

    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:

    1. the delete on the Newton Backend of a specific user logged with a Login Flow
    2. if the global stateChangeListener is set it is invoked
    3. an analytic event of Logout is sent

    Warning

    The user must be logged in with Any Login Flow except from Custom

    Declaration

    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

  • 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

    public 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

    public 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

    public 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

    public 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

    public 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

    public 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

    public 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

    public 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

    public 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

    public 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 begun

    Throws

    EventAnalyticError if there is no Analytic Flow in progress

    Declaration

    Swift

    public 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

    public 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

  • Dummy Method only for Frameworks alignments

    Declaration

    Swift

    public func flushEvents(flushCallback callback: NWCallback)

    Parameters

    callback

    a callback