//[[sdk:basics|Mobile SDK]]//

====== Shared Instance ======

==== Overview ====

Use this method to access the main object with which you can access to all the API functionality.

==== Signature ====

<code>
+ (Messangi *)sharedInstance;
</code>

==== Usage ====

<code>
Messangi *messangi = [Messangi sharedInstance];
</code>


==== Returns ====

This method returns the shared instance of the Messangi's object.

====== Init Messangi ======

==== Overview ====

One of the first init steps, this method will start the Fences & Beacon monitoring process.

==== Signature ====

<code>
- (void)initMessangi:(BOOL)first;
</code>

==== Parameters ====

^ Parameter Name ^ Description ^ Possible Values ^
| first | Indicates if this user is already registered so all related services will start at this point. If not registered an additional dialog will be shown, allowing the user to register his mobile number. | <color blue>true</color> \\ <color red> false </color> |

==== Usage ====

<code>
[[Messangi sharedInstance] initMessangi:true];
</code>

====== Init Messangi ======

==== Overview ====

One of the first init steps, this method will start the Fences & Beacon monitoring process.

==== Signature ====

<code>
- (void)initMessangi;
</code>

==== Parameters ====

None

==== Usage ====

<code>
[[Messangi sharedInstance] initMessangi:true];
</code>

====== Set App Name ======

==== Overview ====

Set the Name for your App, useful if you have more that one iOS App to use with Messangi SDK

==== Signature ====

<code>
- (void)setAppName:(NSString *)newName;
</code>

==== Parameters ====

^ Parameter Name ^ Description ^ Possible Values ^
| newName | The desired app name | [[https://developer.apple.com/library/ios/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/|NSString]] * |

==== Usage ====

<code>
[[Messangi sharedInstance] setAppName: @"example_app_name"];
</code>


====== Set the Client Identification ======

==== Overview ====

As part of the initialization process you need to set you ID as a client to Messangi SDK, this allow Messangi SDK to route properly your traffic to your App.

==== Signature ====

<code>
- (void)setClientID:(NSString *)newClientID;
</code>

==== Parameters ====

^ Parameter Name ^ Description ^ Possible Values ^
| newClientID | Your Client ID | [[https://developer.apple.com/library/ios/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/|NSString]] * |

==== Usage ====

<code>
    [[Messangi sharedInstance] setClientID: @"example_client_id"];
</code>

====== Set the Client Private Key ======

==== Overview ====

When you complete the registration process with the Messangi SDK team, you will receive some credentials values as a Messangi's client.

One of those credentials is a private key, you need to use this private key when you are conecting your app with [[sdk:basics|Messangi SDK]]. The SDK will use it internally to sign properly all your requests.

<WRAP round tip>The **private key** will never leave your app scope.</WRAP>

==== Signature ====

<code>
- (void)setApiClientPrivateKey:(NSString *)newPrivateKey;
</code>

==== Parameters ====

^ Parameter Name ^ Description ^ Possible Values ^
| newPrivateKey | Your Messangi SDK private's key | [[https://developer.apple.com/library/ios/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/|NSString]] * |

==== Usage ====

<code>
[[Messangi sharedInstance] setApiClientPrivateKey: @"example_private_key"];
</code>

====== Set the Subscription URL ======

==== Overview ====

This URL is related to the Campaign Manager where you want to have and manage your distribution lists. It will be used every time the user wants to join or leave a distribution list.

==== Signature ====

<code>
- (void)setSubscriptionURL:(NSString *)newURL;
</code>

==== Parameters ====

^ Parameter Name ^ Description ^ Possible Values ^
| newURL | The desired URL | [[https://developer.apple.com/library/ios/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/|NSString]] * |

==== Usage ====

<code>
[[Messangi sharedInstance] setSubscriptionURL:@"example_url_base/rest/api"];
</code>

====== Set the Subscription Workspace ID ======

==== Overview ====

This ID is related to the workspace on the Campaign Manager which you want to work with. It will be used every time the user wants to join or leave a distribution list.

==== Signature ====

<code>
- (void)setSubscriptionInstanceID:(NSString *)newID;
</code>

==== Parameters ====

^ Parameter Name ^ Description ^ Possible Values ^
| newID | The desired workspace ID | [[https://developer.apple.com/library/ios/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/|NSString]] * |

==== Usage ====

<code>
[[Messangi sharedInstance] setSubscriptionInstanceID:@"example_workspace_id"];
</code>


====== Subscribe the device with Messangi SDK ======

==== Overview ====

As part of the initialization process, this method will establish a bind between the device and the Messangi SDK, this bind will be used for sending PUSH notifications to the device.

This method is used internally by [[sdk:ios_api#register_device_token|registerDeviceToken]] method.

==== Signature ====

<code>
- (void)deviceSubscriberWithUniqueID;
</code>

==== Usage ====

<code>
[[Messangi sharedInstance] deviceSubscriberWithUniqueID];
</code>

====== Register Device Token ======

==== Overview ====

Generates an unique device identifier and register the device with Messangi SDK.

==== Signature ====

<code>
- (void)registerDeviceToken:(NSData *)deviceToken;
</code>

==== Parameters ====

^ Parameter Name ^ Description ^ Possible Values ^
| deviceToken | This is the device token Apple provides when register your app with the APNs, you will receive this parameter through [[https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIApplicationDelegate_Protocol/index.html?hl=ar#//apple_ref/occ/intfm/UIApplicationDelegate/application:didRegisterForRemoteNotificationsWithDeviceToken:|didRegisterForRemoteNotificationsWithDeviceToken]] method | [[https://developer.apple.com/library/ios/documentation/Cocoa/Reference/Foundation/Classes/NSData_Class/|NSData]] |

==== Usage ====

<code>
[[Messangi sharedInstance] registerDeviceToken:deviceToken];
</code>

====== Refresh Monitored Regions ======

==== Overview ====

In iOS like in other mobile OS it's possible to monitor geographical regions, by monitoring it, the device is capable of trigger an event when gets inside of a given area. Unfortunately iOS limits the amount of simultaneous geographical fences to 20. Read more about this at the [[https://developer.apple.com/library/ios/documentation/UserExperience/Conceptual/LocationAwarenessPG/RegionMonitoring/RegionMonitoring.html|Developer's Apple]] online documentation.

This method will review the proximity and conditions of all relevant GeoFences and select the closest 20 from the global list to keep track of those, please note that this method will also be used by Messangi SDK itself.
==== Signature ====

<code>
- (void)refreshMonitoredRegionsToClosest;
</code>

==== Usage ====

<code>
[[Messangi sharedInstance] refreshMonitoredRegionsToClosest];
</code>

====== Subscribe To Distribution List ======

==== Overview ====

You can create multiples Distribution Lists with the [[:campaign_manager|Campaign Manager]] to reach different user's groups.

Those Distributions Lists can be populated using multiples techniques, this method allows the user to suscribe to a List.


==== Signature ====

<code>
- (void)subscribeToList:(NSString *)subscriptionID;
</code>

==== Parameters ====

^ Parameter Name ^ Description ^ Possible Values ^
| subscriptionID | The subscription id to be added | [[https://developer.apple.com/library/ios/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/|NSString]] * |


==== Usage ====

<code>
[[Messangi sharedInstance] subscribeToList:@"example_value"];
</code>

====== Unsubscribe From Distribution List ======

==== Overview ====

You can create multiples Distribution Lists with the [[:campaign_manager|Campaign Manager]] to reach different user's groups.

Registered users can leave a list any time they want, this method allows the user to unsubscribe from a list.


==== Signature ====

<code>
- (void)unsubscribeFromList:(NSString *)subscriptionID;
</code>

==== Parameters ====

^ Parameter Name ^ Description ^ Possible Values ^
| subscriptionID | The subscription id to be removed | [[https://developer.apple.com/library/ios/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/|NSString]] * |

==== Usage ====

<code>
[[Messangi sharedInstance] unsubscribeFromList:@"example_value"];
</code>

====== Passing incoming PUSH to Messangi ======

==== Overview ====

We recommend when using [[sdk:basics|Messangi SDK]] passing every PUSH notification you receive to the SDK first, if the PUSH is not relevant to the SDK it will let you handle the message your own way.

The SDK spect multiples message types, most of those are silent to the user, that's why we recommend to let the SDK process the incoming PUSH notification first.

==== Signature ====

<code>
- (BOOL)didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler;
</code>

==== Parameters ====

^ Parameter Name ^ Description ^ Possible Values ^
| userInfo | Holding the **msgId** and **type** values | [[https://developer.apple.com/library/ios/documentation/Cocoa/Reference/Foundation/Classes/NSDictionary_Class/|NSDictionary]] * |
| completionHandler | Handler to be notified when completed | void (%%^%%)(UIBackgroundFetchResult) |

==== Usage ====

<WRAP round tip>
When you are working with PUSH notifications you need to override the **didReceiveRemoteNotification** method, we recommend to do it as follow to ensure the SDK work properly.
</WRAP>

<code>
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
{
    if ([[Messangi sharedInstance] didReceiveRemoteNotification:userInfo fetchCompletionHandler:completionHandler]) {
        /*
         * Messangi SDK already handled the PUSH notification
         * You can add code here to performing an additional operation
         */
    } else {
        /*
         * Notification received was not wanted by Messangi
         * This notification must be managed by host App here
         */
    }
}
</code>

==== Returns ====

<color blue>true</color> if the PUSH was processed by the SDK, <color red>false</color> if not

====== Get Unread Messages ======

==== Overview ====

This method is used internally by messangi's [[sdk:ios_api#passing_incoming_push_to_messangi|didReceiveRemoteNotification]] method. It will fetch all pending messages you have stored at Messangi.
==== Signature ====

<code>
- (void)getUnreadMessages;
</code>

==== Usage ====

<code>
[[Messangi sharedInstance] getUnreadMessages];
</code>


====== Start Location Services ======

==== Overview ====

Start Apple's Location Services from [[https://developer.apple.com/library/ios/documentation/CoreLocation/Reference/CoreLocation_Framework/|CoreLocation Framework]]. This method is internally called by [[sdk:ios_api#init_messangi|initMessangi]] method.

==== Signature ====

<code>
- (void)startStandardUpdates;
</code>

==== Usage ====

<code>
[[Messangi sharedInstance] startStandardUpdates];
</code>


====== Report Current Location ======

==== Overview ====

This in an internal method, this method report the current device location and is automatically fired by [[sdk:ios_api#passing_incoming_push_to_messangi|didReceiveRemoteNotification]] method.

==== Signature ====

<code>
- (void)sendLastLocationForMsgID:(NSString *)msgID withHandler:(void (^)(UIBackgroundFetchResult))completionHandler;
</code>

==== Parameters ====

^ Parameter Name ^ Description ^ Possible Values ^
| msgID | The incoming message id for which the location is reported | [[https://developer.apple.com/library/ios/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/|NSString]] * |
| completionHandler | Handler to be notified when completed | void (%%^%%)(UIBackgroundFetchResult) |

==== Usage ====

<code>
[[Messangi sharedInstance] sendLastLocationForMsgID:ex_msgID withHandler:ex_completionHandler];
</code>

====== Location Services Status ======

==== Overview ====

This method verifies if the location services are ON at the moment

==== Signature ====

<code>
- (BOOL)statusLocationServicesOK;
</code>

==== Usage ====

<code>
[[Messangi sharedInstance] statusLocationServicesOK]
</code>

==== Returns ====

<color blue>true</color> if the location service is ON, <color red>false</color> if not

====== Monitored GeoFences ======

==== Overview ====

Return all GeoFences currently monitored by the App.

==== Signature ====

<code>
- (NSSet *)monitoredGeoFences;
</code>

==== Usage ====

<code>
[Messangi monitoredGeoFences]
</code>

==== Returns ====

[[https://developer.apple.com/library/ios/documentation/Cocoa/Reference/Foundation/Classes/NSSet_Class/|NSSet]] containing [[https://developer.apple.com/library/ios/documentation/CoreLocation/Reference/CLRegion_class/|CLRegion]] objects, each one represents a monitored GeoFence.

====== Log Event ======

==== Overview ====

Log events with [[sdk:basics|Messangi SDK]], they will be available to review later in our [[https://www.elastic.co/products/kibana|Kibana]]

==== Signature ====

<code>
- (void)logEvent:(NSString *)eventType andExtraInfo:(NSString *)extraInfo;
</code>

==== Parameters ====

^ Parameter Name ^ Description ^ Possible Values ^
| eventType | DESCRIPTION | [[https://developer.apple.com/library/ios/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/|NSString]] |
| extraInfo | Additional information to storage | [[https://developer.apple.com/library/ios/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/|NSString]] |

==== Usage ====

<code>
[[Messangi sharedInstance] logEvent:@"example_type" andExtraInfo:@"example_additional_info"];
</code>