Connecting to a portal

Conceptually, a user always connects to a portal to access GIS content. If users are part of an organization subscription, they 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 that is informed when operations on the portal complete successfully or encounter an error.

Initiate a connection

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

URL points to a general portal

If the URL points to a general portal and if no credential is provided, AGSPortal connects to that portal as an anonymous user. The example below shows how to connect to the portal as an anonymous user.

NSURL *url = [NSURL URLWithString:@"”];
self.portal = [[AGSPortal alloc] initWithURL:url credential:nil];
When you create the portal object, you need to ensure its memory does not get deallocated before it has a chance to execute. To do this, you need to retain the portal object if you're using manual retain-release, or create a strong reference to it if you're using ARC. See Apple's Memory Management Programming Guide for more information on how to manage object memory.

Credential is provided

If a credential is provided, AGSPortal transparently connects to an organization's subscription within that portal if the credentials belong to a user who is authorized to access the subscription. Therefore, in the example below, if the user john_doe belongs to an organization's subscription within, the portal automatically connects to that subscription.

NSURL *url = [NSURL URLWithString:@””];

AGSCredential *credential = [[AGSCredential alloc] initWithUser:@"john_doe" password:@"<password>"];
//Must provide authType and tokenUrl 
credential.authType = AGSAuthenticationTypeToken;
credential.tokenUrl = [NSURL URLWithString:@""];   

self.portal = [[AGSPortal alloc] initWithURL:url credential:credential];

If credentials don't belong to a subscription user, AGSPortal connects to the general portal as that user.

URL points to a specific organization's subscription

If the URL points to a specific organizations's subscription within a portal, AGSPortal connects to that subscription. If the subscription allows anonymous access, a credential is not required for the connection. Otherwise, provide the credentials of a user who is authorized to access the subscription.

NSURL *url = [NSURL URLWithString:@"”];

//Credential to access the portal
AGSCredential *credential = [[AGSCredential alloc] initWithUser:@"john_doe" password:@"<password>"];
self.portal = [[AGSPortal alloc] initWithURL:url credential:credential];

Verify the connection was successful

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

self.portal.delegate = self;

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>     

//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


You may encounter connection problems if the portal's digital certificate is not signed by a trusted root server. When this happens, you get an error code of type NSURLErrorServerCertificateUntrusted. Work around this problem by adding the host name of the portal to the list of trusted hosts as follows:

if([error code] == NSURLErrorServerCertificateUntrusted){

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

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

When you successfully connect to a specific subscription, information about the portal and organization who owns the subscription returns in the AGSPortalInfo object. However, when you connect just to the general portal, only information about the portal returns. 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 organization, a thumbnail image, and so on. This information is encapsulated in an AGSPortalInfo object which is available through the portalInfo property on AGSPortal.

See Also