Pal+ SDK

Prerequisite

• iOS >= 7.0
• Cocoapods
• iOS Device with Pal+ app installed (SDK integration not work in simulator)

Installation

• Configure SDK dependencies in Podfile

  pod "palplus-sdk-ios", :git => "https://github.com/palplus-api/palplus-sdk-ios.git", :tag => "x.y.z" 
  

• install pod dependency with pod install

• SDK Initialization

  • With full feature (including Forum & Messenger integration)

    In your UIApplicationDelegate, initialize the PalPlus SDK with [PALSdk setup:_YOUR_APP_KEY_]. You have to go to Pal+ developer console to register for an app key for you app to use Messenger API. Please refer to Register App Key for details.

  - (BOOL)application:(UIApplication *)application 
              didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      NSString* appKey = @"_YOUR_APP_KEY_";
      [PALSdk setup:appKey];
      return YES;
  }
  
  - (BOOL) application:(UIApplication*) application
   	 openURL:(NSURL*) url
      sourceApplication:(NSString*) sourceApplication
         annotation:(id) annotation {
     return [PALSdk handleOpenUrl:url sourceApplication:sourceApplication];
  }
  
  

  In order for users to open your app after clicking on the message button, you have to define a URL scheme in info.plist to receive an URL triggered by Pal+

  • add a scheme palplus-sdk-__YOUR_APP_KEY__ as URL types -> Item 0 -> URL Schemes -> Item 0
  • configuration sample:

  

  • With Forum API only

    In your UIApplicationDelegate, initialize the PalPlus SDK with [PALSdk setup:nil], no need to define URL scheme in info.plist

Messenger API Usage

App startup Connection

In order to use Messenger API, the user has to connect your app with their Pal+ profile. Call [PALSdk messenger] connect: method to ask for user's authorization.

- (void) viewDidLoad {
  [super viewDidLoad];

  UIButton* connectButton = [[PALSdk messenger] connectButton];
  [connectButton addTarget:self action:@selector(openPalPlus) forControlEvents:UIControlEventTouchUpInside];
  [self.view addSubview:connectButton];
}

- (void) openPalPlus {
  [[PALSdk messenger] connect:^(BOOL success) {
    if (success) {
       NSLog("Messenger API is ready");
    }
  }];
}

After the user accepts your app's request to connect Pal+, the protocol PALMessenger can be used.

Request profile

requestMe: returns the nickname and icon of the connected user

  [[PALSdk messenger] requestMe:^(PALUser* user, NSError* error) {
    if (error) {
      NSLog(@"requestMe fail:%@", error);
      return;
    }
    NSLog(@"user profile:%@", user);
  }];

Request friends

requestFriends:pageSize:done: returns a list of friends for the connected user with their nicknames and icons

  PALFriendsResult* current = nil;
  [[PALSdk messenger]
      requestFriends:current
            pageSize:PALDefaultFriendListPageSize
                done:^(PALFriendsResult* updatedFriendsResult, NSError* error) {
                  if (error) {
                    NSLog(@"requestFriends fail:%@", error);
                    return;
                  }
                  NSLog(@"friend results updated success:%@", updatedFriendsResult);
                }];

To retrieve additional friends, you should pass the result from last request as the first argument of requestFriends:pageSize:done:, Returned updatedFriendsResult include previous and next paging of friends.

Send custom Message

sendMessage: is used to send a custom message to the friends of the connected user. Below is a simple example to send the text "hello" to a specific user.

NSString* friendUid = palFriend.uid;
PALMessageBuilder* builder = [PALMessageBuilder builder];
[builder text:@"hello"];
[builder notification:@"hello notify"];
PALMessage* message = [builder build];
[[PALSdk messenger] sendMessage:messsage to:friendUid done:^(NSError* error) {
    if (error) {
      NSLog(@"sendMessage fail:%@", error);
      return;
    }
    NSLog(@"sendMessage successfully");
  }];

Send custom Message with actions

The custom message is composed of 1 mandatory notification and 4 optional parts, including:

1. text: maximum length is 512
2. image: a web URL, maximum width and height is 250
3. action link: clickable link text, will bring user to your app if installed, Google Play otherwise
4. action button: same as above, will show your app icon defined in Pal+ developer console

Both action link and buttons support additional parameters, which will be passed back to your app when user clicks on them.

// a sample action pass `coin=100&user=john` back to app after user click on message. 
PALMessageActionParams* buttonAction = [[[PALMessageActionParams params]
    executeParam:@"coin=100&user=john"]
    marketParam:@"from=sdk"];
[builder appButton:@"daily gift" action:buttonAction];
[[PALSdk messenger] sendMessage:[builder build] to:friendUid done:^(NSError* error) {...}];

To receive the execute params passed from Pal+ to your app, the protocol PALMessengerDelegate must be implemented and set to [PALSdk messenger].delegate, pal_messenger:didOpenWithExecuteParams: will be called.

- (void) prepare {
  [PALSdk messenger].delegate = self;  //self class implements PALMessengerDelegate
}

- (void) pal_messenger:(PALMessenger*) messenger didOpenWithExecuteParams:(NSString*) params {
  NSLog(@"receive params: %@", params);
}

Handle invalid connection

Connection with Pal+ is automatically refresh periodically in the background. However, if the user has not been using your app for a long time, the connection will be invalid and the method PALMessengerDelegate.pal_messengerConnectionInvalidated: will be called:

- (void) prepare {
  [PALSdk messenger].delegate = self;  //self class implements PALMessengerDelegate
}

- (void) pal_messengerConnectionInvalidated:(id<PALMessenger>) messenger {
  NSLog(@"messenger connection invalidated, You should redirect user to connect Pal+ again");
}

Forum API Usage

• Prepare board ID You can obtain your target forum board id from https://palplus.me/space/ e.g. the board id of Selfie board is the last component of the URL: 94be6940-c24b-11e4-84a2-031799f6bc4f for https://palplus.me/space/global/board/94be6940-c24b-11e4-84a2-031799f6bc4f

• Open board

if ([[PALSdk forum] canOpenBoard:BOARD_ID]) {
  [[PALSdk forum] openBoard:BOARD_ID];
} else {
  NSLog(@"please install pal+ first");
}

• Post article

if ([[PALSdk forum] canCreateArticle:BOARD_ID]) {
  UIImage* image = ... //optional local image
  NSString* title = @"hello"; //optional title of article
  [[PALSdk forum] createArticle:BOARD_ID withTitle:title withImage:image];
} else {
  NSLog(@"please install pal+ first");
}

Demo

• git clone https://github.com/palplus-api/palplus-sdk-ios.git demo
• enter the directory demo/Example
• run pod install
• open example project workspace named demo/Example/palplus-sdk-ios.xcworkspace in XCode