ArcGIS API for iOS - Connecting to a Portal

Conceptually, a user always connects to a portal to access his GIS content. If he is part of an organization subscription, he may connect to a "sandboxed" area of the portal earmarked for that organization.

AGSPortal is the main class and the entry point into the API for working with portals. It has a delegate which is informed when operations on the portal complete successfully or encounter an error.

Initiating a connection

To connect to a portal or an organization's subscription within a portal, you need to instantiate an AGSPortal object. This will prompt a connection to be established in the background. The connection itself is agnostic of what is being connected to, a general portal or a specific subscription, and depends upon the URL and the credential that is used while instantiating the object. There are two cases -

If the URL points to a specific organization's subscription within a portal...

AGSPortal will connect to that subscription. If the subscription allows anonymous access, a credential is not required for the connection. Otherwise, you must provide the credentials of a user who is authorized to access the subscription.

NSURL *url = [NSURL URLWithString:@"http://eyeonearth.maps.arcgis.com”];

AGSCredential *credential = [[[AGSCredential alloc] initWithUser:@"john_doe" password:@"<password>"] autorelease];

//Must provide authType and tokenUrl 
credential.authType = AGSAuthenticationTypeToken;
credential.tokenUrl = [NSURL URLWithString:@"https://www.arcgis.com/sharing/rest/generateToken"];   

AGSPortal *portal = [[[AGSPortal alloc] initWithURL:url credential:credential] autorelease];

Else, if the URL points to a general portal AND ...

If no credential is provided ...

AGSPortal will connect to that portal as an anonymous user. The example below shows how to connect to the www.ArcGIS.com portal as an anonymous user.

NSURL *url = [NSURL URLWithString:@"http://www.arcgis.com”];
AGSPortal *portal = [[[AGSPortal alloc] initWithURL:url credential:nil] autorelease];

Else, If a credential is provided ...

AGSPortal will transparently connect to an organization's subscription within that portal if the credentials belong to a user who is authorized to access the subscription. So, in the example below, if the user 'john_doe' belongs to an organization's subscription within www.ArcGIS.com, then the portal will automatically connect to that subscription.

NSURL *url = [NSURL URLWithString:@”http://www.arcgis.com”];

AGSCredential *credential = [[[AGSCredential alloc] initWithUser:@"john_doe" password:@"<password>"] autorelease];
//Must provide authType and tokenUrl 
credential.authType = AGSAuthenticationTypeToken;
credential.tokenUrl = [NSURL URLWithString:@"https://www.arcgis.com/sharing/rest/generateToken"];   


AGSPortal *portal = [[[AGSPortal alloc] initWithURL:url credential:credential] autorelease];

If credentials dont belong to a subscription user, AGSPortal will connect to the general portal as that user.

Verifying the connection was successful

To verify whether the connection was successful and that information about the portal/subscription were loaded properly, you must set one of your classes as the delegate of AGSPortal.

portal.delegate = self;

You must also adopt the <AGSPortalDelegate> protocol in your class' header file (.h file) and implement the relevant methods in the implementation file (.m file).

//MyViewController.h file
@interface MyViewController : UIViewController <AGSPortalDelegate>     
   ... 
@end


//MyViewController.m file
@implementation MyViewController
  ...
  
   - (void)portalDidLoad:(AGSPortal*) portal {
       //now it is safe to access the portal's properties
   }
   
   - (void)portal:(AGSPortal*) portal didFailToLoadWithError:(NSError*)error {
      //handle or report the error
   }

@end

Note:

You may encounter connection problems if the portal's digital certificate is not signed by a trusted root server. When this happens, you will get an error code of type NSURLErrorServerCertificateUntrusted . You can work around this problem by adding the hostname of the portal to the list of trusted hosts

if([error code] == NSURLErrorServerCertificateUntrusted){

  //add host to trusted list
  [[NSURLConnection trustedHosts] addObject:[portal.URL host]];

  //retry connecting to portal
  [portal resubmitWithURL:url credential:credential] ;
  
}

When you successfully connect to a specific subscription, information about both the portal and the organization who owns the subscription is returned in the AGSPortalInfo object. However, when you connect just to the general portal, only information about the portal is returned. Among other things, the information includes details such as the default base map used in the portal or by the organization, the predefined queries that can be used to find featured groups and items of the portal or the organization, a thumbnail image, etc. This information is encapsulated in an AGSPortalInfo object which is available through the portalInfo property on AGSPortal

Connecting to a Portal