Show TOC

OpenUI Installation Instructions (iOS)Locate this document in the navigation structure

Introduction

As part of OpenUI, the iOS client has been "SDK-ized" into a pseudo framework containing a statically linked library that application designers can use to create an Xcode project and build their custom field adapters with. A sample pre-packaged Xcode project ready to accept field extensions is also provided with the library for ease of use and prototyping extensions easily.

This page contains a description of the pseudo framework contents, instructions on how to incorporate it into an arbitrary Xcode project, and a description of the sample project provided with the framework. Also at the end, see the notes section for hints.

The SMPAgentryClientFramework framework

The resources for OpenUI are delivered as a framework for iOS. Because at the present time Apple does not support the proper creation of dynamic frameworks, the library at the heart of our framework is supposed to be statically linked into the user's applications. This library and the resources provided with the framework contain all the functionality of the iOS Agentry Client. The framework is packaged as a TGZ file which name is in the format SMPAgentryClientFramework-iOS-W.X.Y.Z.tgz (W.X.Y.Z would be the current Agentry Version), and it has the following directory structure:

  • SMPAgentryClientFramework/
    • iOS/
      • SMPAgentryClient.framework/
        • Headers@ -> Versions/Current/Headers
        • Resources@ -> Versions/Current/Resources
        • MPAgentryClient@ -> Versions/Current/SMPAgentryClient
        • Versions/
          • Current@ -> W.X.Y.Z
          • W.X.Y.Z/
            • Headers/
              • SMPOpenUI/ The headers needed for adapters and models of SMPOpenUI
              • SMPDataAPI/ The headers needed for SMPDataAPI
            • Resources/
              • SMPAgentryClientResources.bundle The resource (images, sounds, etc...) needed for Agentry
            • SMPAgentryClient* The static library containing the iOS Agentry Client code
      • Samples/ Xcode sample projects are here, see section below for more details. These are tested with Xcode 5 and 5.1
        • SMPAgentryClientFrameworkDemo/
        • SMPAgentryClientFrameworkSetup/
      • SampleApp/ The sample application Agentry definitions
        • OpenUI-app.agxz The definitions for the sample App exported from the Agentry Editor
        • OpenUIPlayersDB.txt The sample data in SQL query format ready to populate a sample database

The static library

The framework static library is provided with slices for architectures armv7 and asmv7s as well as i386 so your applications can be tested in the simulator and devices alike.

Xcode project setup instructions

These instructions are to setup a new project to use the SMPAgentryClientFramework as well as to add it to an existing project. For ease of use a new project already setup is being provided in the Samples/ directory.

Pre-requisites:

  • A Mac with Xcode 5.1 installed and ready to develop for iOS.
  • The SMPAgentryClientFramework distribution has been expanded into a directory. For the rest of these instructions, we are assuming this was done to the SDK_INSTALL_HOME directory.

Instructions:

  1. Open Xcode and create a new project. Choose iOS Application > Empty Application.
  2. Set the iOS Deployment Target to 6.0 or above for your project.
  3. Set the Architectures and Valid Architectures build settings to $(ARCHS_STANDARD_32_BIT) for your project. (Xcode 5.1 defaults to including arm64 as a standard architecture, but that is not supported by Agentry).
  4. Add the SAP Mobile Platform Agentry Client Framework:
    1. Select the project, the main target, and in Build Settings search for "Framework Search Path"
    2. Double click and enter: SDK_INSTALL_HOME/SMPAgentryClientFramework/iOS/**
  5. Add the SAP Mobile Platform Agentry Client Framework Headers:
    1. Select the project, the main target, and in Build Settings search for "Header Search Path"
    2. Double click and enter: SDK_INSTALL_HOME/SMPAgentryClientFramework/iOS/SMPAgentryClient.framework/Headers/**
  6. Modify linker flags:
    1. Select the project, the main target, and in Build Settings search for "Other Linker Flags"
    2. Double click and enter: -ObjC -framework SMPAgentryClient
  7. Add the required dynamic libraries and frameworks:
    1. Select the project, the main target, and in Build Phases search select the "Link With Dynamic Libraries" section.
    2. Click on the "+" button, and add the following:
      • libc++.dylib
      • libiconv.dylib
      • libicucore.dylib
      • libxml2.dylib
      • AudioToolbox.framework
      • AVFoundation.framework
      • CFNetwork.framework
      • CoreLocation.framework
      • CoreMedia.framework
      • CoreText.framework
      • CoreVideo.framework
      • QuartzCore.framework
      • Security.framework
      • CoreGraphics.framework
      • Foundation.framework
      • UIKit.framework
  8. Remove stripping from the project settings:
    1. Select the project, the Xcode project, and in Build Settings search for "Strip Linked Product"
    2. Double click and select No.
  9. Add the resources bundle:
    1. Go to the Xcode application File menu
    2. Select the Add Files to Project item
    3. Browse to the SDK_INSTALL_HOME/SMPAgentryClientFramework/iOS/SMPAgentryClient.framework/Resources/SMPAgentryClientResource.bundle location, and add it.
  10. Modify the main.m file to launch the Agentry Client:
    1. Replace the app delegate class name with the string @"SMPAgentryClientAppDelegate".
    2. Replace the application class name with the string @"SMPAgentryApplication".
    3. At the end, the return statement should look like this: return UIApplicationMain(argc, argv, @"SMPAgentryApplication", @"SMPAgentryClientAppDelegate");
  11. Set up the app so that view controllers do not determine the style of the status bar.
    1. Modify Info.plist to inclide the following key: UIViewControllerBasedStatusBarAppearance set to false.
  12. Build and launch and the default Agentry Client should come up in the simulator or device.

You can now start adding code for your custom adapters, and the Agentry Client will pick them up dynamically.

Sample Projects

Creating this Xcode project and setting it up can be a tedious process, so that's why as mentioned above, sample projects are provided with the framework for common tasks these are:

SMPAgentryClientFrameworkSetup

This is an empty Xcode project with all the setup instructions from above integrated. Can be used to start developing a brand new app or to prototype sample adapters easily.

SMPAgentryClientFrameworkDemo

This is an Xcode project with sample adapters for our extensible fields provided as well as demo data and an Agentry application. This can be used to learn about the extension mechanisms and classes.

Branding iOS with the SMPAgentryClient Framework

With branding, a customer can personalize the Agentry Client to include their art as well as strings and have the client use these resources even before it connects to the server. The iOS client can be easily branded using the SMPAgentryClientFrameworkSetup sample Xcode project. All the instructions below refer to using the SMPAgentryClientFrameworkSetup sample Xcode project to achieve this branding, but they also apply to any Xcode project that has been set up to use the SMPAgentryClient framework.

Currently, there are three types of resources that can be branded:

iOS Resources

These are resources that the OS uses on behalf of the application even before it launches such as the icon and name to use on the springboard or home screen, the default launch images to use while the app is being loaded for the first time, etc. These are the resources usually specified for an application in the Info.plist PLIST file.

To brand or change these resources, the customer just needs to modify the *Info.plist file in the SMPAgentryClientFrameworkSetup sample Xcode project to change the strings in the strings case or add their desired images to the application main bundle with the expected names (Default.png, Icon.png, etc ...). More information on the format these files must have can be found in Apple's website at: https://developer.apple.com/library/ios/documentation/general/Reference/InfoPlistKeyReference/Articles/AboutInformationPropertyListFiles.htmlInformation published on non-SAP site

Agentry Resources

These are resources that the Agentry Client application uses by default before it has connected to the server. These include things such as the Login Dialog Image or the About Dialog Image. These resources are delivered as part of the SMPAgentryClientResources.bundle bundle that comes with the framework and is part of the SMPAgentryClientFrameworkSetup sample Xcode project as well.

To brand or change these resources, the customer just needs to add a file of the same name and size to the main bundle of their new app. The Agentry Client will give preference to using these resource files when present over the ones in the bundle.

Agentry Strings

These are localizable strings that are used throughout the Agentry Client User Interface. These can be overridden via the server mechanism, but they can be branded as well in order to customize the app even before the initial transmit.

To brand or change these resources, the customer just needs to add a file to the main bundle of their app called Branding.plist. This file should have a all the required strings in a dictionary with the format [key: String_N value: the new value] where N is the number of the resource string in the Agentry string resources file ClientText.ini. For instance, the following Branding.plist file:

<?xmlversion="1.0"encoding="UTF-8"?>
<!DOCTYPEplistPUBLIC"-//Apple//DTDPLIST1.0//EN""http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plistversion="1.0">
<dict>
<key>String_6155</key>
<string>FunwithBrandedApps</string>
</dict>
</plist>

Will change string 6155 (the Login Dialog Caption) from "Welcome to Agentry" to "Fun with Branded Apps".

There are a few special strings that can be added to this file:
  1. agentryServerUrl will provide a default URL for a server that will prevent the user from being able to select their server URL.
  2. For ANGEL connections, use agentryServerAddress and agentryServerPort to brand the server address and port respectively into the file for the same effect as above. (deprecated)
Notes

If you are trying to integrate a library that requires you to include the -all_load linker flag. Do not do that because the Agentry Client includes libraries that do not handle this option. Instead, use the option -force_load path/to/the/library which will have the same effect on only that library. For a full technical note from Apple, visit this page: https://developer.apple.com/library/mac/#qa/qa2006/qa1490.htmlInformation published on non-SAP site

If your directory paths have spaces, please enter them using double quotes such as "SDK_INSTALL_HOME/path with spaces/SMPAgentryClientFramework/iOS/**" or Xcode will think they are different compiler/linker options.

The sample projects have been tested with Xcode 5, Xcode 5.1 together with iOS 6.x, iOS 7.0, and iOS 7.1.