Skip to content

Creating Apps with the SAP Cloud Platform SDK for iOS Assistant

The SAP Cloud Platform SDK for iOS Assistant facilitates application development by providing a simple and efficient way for developers to implement various technical tasks. It connects to SAP Cloud Platform so that the developer can quickly define and configure the application, add OData services, define authentication, and so on. You can also use the Assistant to enable features such as logging and push notifications on your generated app.

Developers using the SDK must perform the same technical and implementation tasks for every application, which include, but are not limited to:

  • Creating the Xcode project
  • Registering the app with SAP Cloud Platform
  • Configuring various SAP Cloud Platform services
  • Accessing a back-end OData service or consuming one via the API Business Hub or a Developer Portal
  • Adding references to various SAP and Apple libraries and frameworks

App developers can streamline this process by using the Assistant to generate an iOS reference application that:

  • Contains code that performs these tasks in a manner recommended by SAP
  • Includes the correct references to the required SAP and Apple libraries
  • Sets the necessary capabilities in the application property list file

You require an SAP Cloud Platform account with administrator privileges to create or edit configuration settings on the SAP Cloud Platform. The Assistant supports both Cloud Foundry (CF) and Neo environments.

Choose Your Project Template

The SAP Cloud Platform SDK for iOS Assistant offers different templates that guide you through the app generation process. Depending on the template you select, more or fewer steps will be required and need your attention. You can always go back and make further changes either in the SAP Cloud Platform Mobile Services Cockpit or in the Assistant in the Manage Projects area.

Launch the Assistant, select Create new and choose one of the following.

Tip

The Sample Application is the easiest way to generate an app with the least user input. You only need to provide a name and identifier for your app. All other configuration settings, such as destination configuration, are completed automatically using the ESPM sample service.

Create New Application

The Create New Application scenario provides the most flexibility and options for creating a mobile application.

  1. From the Account screen, enter the mobile services account to be used by the mobile app.

  2. From the Cloud Application screen, enter the values used to create the application.

  3. From the Destinations screen, add new or select existing OData destinations to be consumed by your application.

  4. From the Features screen, select the features you want to enable.

  5. From the Xcode Project screen, configure the properties that generate a new Xcode project.

  6. From the Proxy Classes screen, edit and generate proxy classes for the selected destinations.

  7. From the UI Configuration screen, configure the UI for the application.

Reuse Existing Application

Select an existing Cloud application configuration and use it as the basis for a new application.

  1. From the Account screen, enter the mobile services account to be used by the mobile app.

  2. From the Cloud Application screen, select an existing application definition from the list, which is downloaded from SAP Cloud Platform mobile services.

  3. From the Xcode Project screen, configure the properties that generate a new Xcode project.

  4. From the Proxy Classes screen, edit and generate proxy classes for the selected destinations.

  5. From the UI Configuration screen, configure the UI for the application.

Sample Application

Use the sample application scenario to create your first application, providing a given configuration with populated properties and a predefined back-end configuration.

Create a basic sample application that uses a predefined sample OData destination.

  1. From the Account screen, enter the mobile services account to be used by the mobile app.

  2. From the Cloud Application screen, enter the values used to create the sample application.

    Note

    The sample application scenario uses OAuth2 as its preconfigured authentication method.

  3. From the Xcode Project screen, configure the properties that generate a new Xcode project.

Generated Application

If you selected the Onboarding or Master/Detail Screens for all Destinations option from the UI Configuration screen, the generated application opens in a Split View, and starts with a Logon screen that uses the authentication type specified earlier. After a successful logon, the application lists the OData Service collections that are available. Selecting a collection displays the first 20 entities. You can select each entity to see its details.

A README file is added to the project, containing project information, links to tutorials, and other helpful information.

Run the sample application from Xcode and see the results in the simulator.

  1. Select the Run icon to view the application in the simulator. The application results are displayed on the simulator.

  2. There are several screens you need to pass through before you see the application:

    1. Select Start on the Welcome Screen.
    2. Sign into your SAP Cloud Platform account using your user ID and password.
    3. Select Allow on the Data Privacy and Usage Data Collection screens.
    4. Set a passcode in the Choose Passcode screen.
    5. Select Allow when asked about being sent notifications.

Next Steps

Once you've generated your app, you need to customize it as required.

You can extend your app with SAPFiori components (Onboarding, Branding and Theming, Object-related controls, and so on) using the SAP Fiori for iOS Mentor mobile application. You can access and download the SAP Fiori Mentor app from the Apple App Store or from the Assistant by selecting HelpDiscover SAP Fiori Mentor Application.

Further configure and administer your native application from the mobile services cockpit as needed, particularly for features that are not configured by the Assistant, such as offline application configuration.

Developing Apps With the Assistant

Use the SAP Cloud Platform SDK for iOS Assistant as the central entry point for creating and managing scenario-based applications that implement SDK features, providing mobile services integration, and supporting other features, such as API and translation services.

The Assistant automatically generates hundreds of lines of source code. For example, it uses the OData service definition to generate specific functions and calls to retrieve data from the mobile services for each entity type, allowing the application to communicate with the back-end system using only the generated code.

The Assistant supports both Cloud Foundry CF and Neo environments. The Assistant interface is essentially the same whether you connect to the Cloud Foundry or Neo environment.

Note

The Assistant uses the Keychain to securely store user data for the connection.

Cloud Configuration

Select an Account

From the Account screen, enter the mobile services account to be used by the mobile app. You can select an existing account, create a new one, or if there are multiple matching accounts, you can select between them.

See Adding the Mobile Services Account for details.

Application Details

From the Cloud Application screen, enter the values used to create the new cloud application. You are prompted to log in to your mobile services account.

  • Name – the name of the application, which can contain alphanumeric characters, spaces, underscores, and periods, and can be maximum of 80 characters.
  • Identifier – unique application identifier in reverse-domain notation. The Assistant registers the application with this ID in the mobile services, and the generated client application uses this ID when sending requests to the SAP Cloud Platform. An application ID:
    • Must be unique
    • Must start with an alphabetic character
    • Can contain only alphanumeric characters, underscores, and periods
    • Can contain up to 64 characters
    • Cannot include spaces
    • Cannot begin with a period, and cannot contain two consecutive periods. SAP recommends you assign IDs that contain a minimum of two periods, for example, com.sap.mobile.app1.
    • Cannot be any of these case-sensitive keywords: Admin, AdminData, Push, smp\_cloud, resource, test-resources, resources, Scheduler, odata, applications, Connections, public, lcm
  • Authentication Type – the type of the authentication used to connect to the Mobile Services Admin API. You can select one of the following authentication types: Basic (requires SAP Identity Provider if using Cloud Foundry), OAuth (default), SAML, and No Authentication (not available on Cloud Foundry). No sensitive data is stored on the device. Users must enter credentials each time they restart the app.

Select Destinations

From the Destinations screen, add new or select existing OData destinations to be consumed by your application. You can also add destinations from an API Management account.

OData Destinations

Select Add new to add a new OData destination or click on an existing destination to select it. Once selected, you can right-click the destination and click Edit to modify it.

If you add a new destination or edit an existing one, provide the destination details:

  • Name – name of the back-end endpoint, which is automatically filled in for the destination.
  • Back-end URL – the OData endpoint URL.
  • Proxy Type – On Premise or Internet.
  • URL Rewrite Mode – can be configured to determine where to rewrite the URL.
  • Maximum Connections – the number of allowed parallel connections.
  • Authentication Type – the authentication type used between the mobile service and the OData endpoint.

The cloud platform supports more authentication types than the Assistant. If you edit a destination from the Assistant, and the destination's authentication type is not supported by the Assistant, a message informs you that the authentication type is not supported. You can proceed with the authentication type using the Assistant, but you can only modify the authentication type from the mobile services cockpit.

See Managing Destinations on SAP Cloud Platform Mobile Services for details.

API Management Destinations

Select Add New from API Management to add Developer Portal access. This requires Adding the Developer Portal (API Management) Account.

Then, depending on the API Management option you selected, see Consuming APIs from the SAP API Business Hub or Consuming APIs from a Developer Portal for implementation details.

Manage Features

From the Client Features screen, select the features you want to enable.

Logging

Upload stored logs from the generated app to the mobile service. For additional information, see the following topics for more information:

  • Logger API
  • LogUploader API
  • Logging for general guidelines
  • Uploading and Viewing Client Logs for a task flow that guides you through configuring log upload and viewing client logs stored on the mobile services
Client Usage

Allows the app to collect and upload information about the application, runtime environment, and any user behavior tracked by the developer to Mobile Services. Administrators can access the data in the mobile services Cockpit at AnalyticsClient Data report for Neo and AnalyticsUser Data for Cloud Foundry. It is the developer's responsibility to ensure that regional regulations are adhered to, and that proper disclosures and consent are gathered from users.

For additional information, see Default Client Usage Implementation.

Remote Notifications

Configure the generated application to accept remote notifications. Configuring remote notifications end-to-end requires additional configuration in both Xcode and the mobile service.

In addition to selecting Enable Remote Notifications, the app developer must also manually enable remote notification capability in Xcode, which is described in Enable push notifications.

For additional information, see Configuring Push Notifications.

When remote notifications are fully and properly configured, the application:

  1. Asks for permission to allow remote notifications.
  2. Registers the device with the mobile service remote notification service.
  3. Receives remote notifications, and displays them in the UI.
OData Provider

The Enable Online OData or Offline OData option determines whether the generated app is an offline or online app. Selecting Offline allows the user to access sync functionality and all data from the Offline store in the generated app.

Discovery Service for Application Bootstrapping

Allows you to publish the configuration to the Discovery Service. If enabled, the generated app must use Discovery Service in the onboarding flow configuration (rather than a hard-coded file). If using the Discovery Service, the generated project does not retrieve configuration data from a ConfigurationProvider.plist file. Instead these details are downloaded from the mobile services, which requires an email address to identify the mobile services instance by the Discovery Service. See App Configuration Using a Discovery Service Provider and Enabling Applications to Discover Configurations

Client Configuration

Create an Xcode Project

From the Xcode Project screen, configure the properties that generate a new Xcode project.

  • Product Name – the name of your Xcode project and the name of the application, which becomes part of the bundle identifier.
  • Organization name and Identifier – required fields that identify the organization, for example, SAP and com.sap.
  • Bundle Identifier – generated from previously provided information.
  • Path – the folder for the generated Xcode project.
  • Mac Catalyst – Enable Mac Catalyst support for the generated Xcode project.

Configure Proxy Class Generation

From the Proxy Classes screen, you can edit and generate proxy classes for selected destinations. Hover over an entry to open the detail pop-up that also includes the Edit button.

  • Generate Proxy Class for the Destination– (optional) defines if proxy classes should be generated for each destination, and is enabled by default. A use case where the developer would want to disable this option is for non-OData destinations. Only enabled destinations will be available from the UI Configuration screen.
  • Service Class Name – (optional) use the OData service property and the class prefix for generated class names.
  • Generated Class Prefix – (optional) a prefix that is assigned each generated OData proxy class.
  • Additional parameters – (optional) general purpose free-text field that allows you to pass in a parameter string directly to the proxy generator.
  • Generate optionals for nullable and non-nullable entity properties – If activated, the proxy class generation will generate Swift optionals for all nullable and non-nullable entity properties. This can be useful if you are selectively loading properties and want to avoid potential crashes when trying to access non-nullable properties that have not been loaded from the server.
  • Local metadata – (optional) may be required if the metadata is not available from the server or is inaccessible from the Assistant, in which case click Select and locate the metadata locally. Also see Proxy Classes.

The Assistant generates proxy classes for the application based on the metadata file of the OData endpoint. The metadata contains an Entity Data Model (EDM), which is a specification for defining the application data.

See:

  • SAPOData for proxy class and implementation details
  • OData Development for information about both offline and online OData

UI Configuration

From the UI Configuration screen, select the application template type to generate and click Finish to generate the application. For Onboarding and Master-Detail options, the Assistant generates a template with Swift classes, default UI screens, as well as code based on selected features that do not have a UI. For example, if you selected Enable Log Upload and Enable Remote Notifications features (which do not include a UI), these features are enabled in the generated code.

The options below are increasingly inclusive. That is, if you select the Onboarding option, the functionality of the Single View option is included as well.

  • Single View – generates the proxy classes for the destinations that represent the OData classes, where the user selected to generate them.
  • Onboarding – enhances the generated application with onboarding to the Mobile Services application. This option allows developers who want to start a new project and don’t need the master/detail views, to leverage the convenience of the onboarding flow implementation.
  • Master-Detail Screens for all destinations – enhances the generated application with a Master-Detail UI for the selected OData destination, and also provides a Controller to properly initialize the DataService. See Structure of the Generated Application to understand the structure of the generated application.

Manage Accounts

Manage the various accounts that include information about the mobile services landscape where the application configuration is created or from which an existing application can be selected. You also establish mobile services that the application can utilize.

  1. From the Assistant launch screen, click Manage Accounts.
  2. You can select and edit an existing account or click Add new to add either a new Mobile Services, Developer Portal, or Translation Hub account as described below.

    • The Visit Account button on the Edit Account screen takes you directly to the mobile services cockpit defined by the UI URL field of the account. This allows you to quickly check status or manage mobile services.
    • The Remove button on the Manage Accounts screen allows you to remove accounts from the list of existing accounts. The button is available for all account types.

Establish an SAP Cloud Platform trial account, then enable the mobile services you require for your particular scenario for that account. From the Assistant home page, select Manage Accounts. Next, depending on which scenario you are implementing, add any of the following services.

Mobile Services Account

The Assistant supports both Cloud Foundry and Neo environments. The Mobile Services interface is essentially the same regardless of what environment you are connecting to.

Enter the mobile services URLs to fill the Add Account or Account Details screen of the Assistant. This requires the Administrator role in the SAP Cloud Platform.

  • Name – name of the Mobile Services account. You can freely choose a descriptive name, which is used throughout the Assistant to reference this Mobile Services account.
  • API URL – URL to access the mobile services Admin API. You can find the Admin API and Admin UI URLs on the Important Links page of the mobile services cockpit. To access this page, log in to the SAP Cloud Platform, navigate to the Mobile Services service, then select the Important Links link on the bottom of the left navigation pane.
  • UI URL – the cockpit URL. When you provide the API URL, the UI URL is filled with a matching default value.

    Note

    Editing the UI URL – is not currently supported on Cloud Foundry and is disabled in the Assistant.

  • Authentication – one of the following:

    • Basic – enter:
      • User – user who is assigned the Administrator role. See Set Up Customer Accounts
      • Password – password for the admin user.
    • Single Sign-On – The Assistant supports Single Sign-On authentication when connecting to the API URL of Mobile Services, which is useful for customers that have SAP Cloud Platform accounts protected by a custom identity provider. When Single Sign-On is selected, the Assistant opens a web view when it connects to the API URL to authenticate with SAML.

Once configured, you can edit, or add additional SAP Cloud Platform Mobile Service accounts from the Assistant's Account screen.

Developer Portal (API Management) Account

You can generate an application from the Assistant that consumes OData services (which are also known as OData APIs) via Developer Portals. A Developer Portal is an application that provides a common platform for application developers to consume APIs. Every API Management customer is provided with his or her own Developer Portal application on the cloud. The Developer Portal offers capabilities for onboarding application developers, exploring and testing APIs, and creating and subscribing to applications.

Note

Enable your SAP Cloud Platform account as described in Creating and Enabling an SAP Cloud Platform Mobile Services Account.

  1. From Services, search for and select the API Management tile.

  2. Click Enable.

  3. Select Access Developer Portal.

  4. Enter the Name of the API Management Account and Developer Portal Host in the Add Developer Portal Account screen from the Assistant. Locate the host value used to access the Web Developer Portal application of Access Developer Portal from the API Management Service on the Cloud Platform.

For more information about API management services, visit SAP Cloud Platform API Management

Add a Translation Hub Account

See Localizing iOS Apps for details.

Consuming APIs

Overview

API management is the process of publishing, promoting, and overseeing APIs in a secure and scalable manner. The Assistant is integrated with API Management to support browsing from exposed services using either the SAP API Business Hub or a Developer Portal instance.

SAP Cloud Platform Mobile Services API Management is an open-extension platform that:

  • Is powered by mobile services, and therefore requires a Mobile Services Account
  • Simplifies integration with SAP and non-SAP solutions
  • Enables sharing digital assets as APIs
  • Connects devices to business transactions
  • Provides enterprise-grade security
  • Ensures optimized performance
  • Helps monitor and manage APIs
  • Provides key management and approval capabilities
  • Supports metering and billing
  • Provides capabilities for registering and exposing services as APIs, and supports REST, OData, and SOAP
  • Enables API developers to define and modify, via policies, the behavior of APIs or services that are decoupled from the integrated target or back-end service
  • Manages access to APIs via quotas during a specific time-period, introducing concurrency access and acceptable spike limits
SAP Business Hub and Developer Portal

SAP API Business Hub is the central catalog of all SAP and partner APIs for developers to build sample apps, extensions, and open integration with SAP. See Discover APIs for more information.

Developer Portal is an application that provides a common platform for application developers to consume APIs. Every API Management customer is provided with his or her own Developer portal application on the SAP Cloud Platform. Supported Developer Portal features include the following:

  • Browse catalog– Explore the product's assembled APIs that are available in the catalog store, navigate to individual API proxies, read the API documentation, and view the resources that are attached to the APIs.
  • Create applications – An application developer can create applications that consume APIs. To consume the APIs, an application developer must subscribe to an application's assembled products. Subscribing to an application returns the key to the developer that allows API access.
  • Onboard an application developer – To explore the APIs and subscribe to an application, an application developer must be registered to the Developer Portal. Once registered, the application developer gains access to the Developer Portal.

See Consume APIs via the Developer Portal for more information about the Developer Portal.

Known Issues and Limitations

Not every API Management feature is supported by the Assistant.

  • Service types – The Assistant handles only OData services while SOAP, REST, and OData services can be exposed via the SAP API Business Hub and Developer Portals. Therefore, when exploring the API products and their services, only OData services are listed when an API product is selected in the Assistant’s catalog browser window:

    • Some services might be OData services, but their service type property might be improperly set to REST. As a result, these services don't appear in the Assistant’s catalog browser.
    • The API Business Hub also offers integration packages that are out of scope and don't appear in the Assistant.
  • Authentication types – Not all authentication types that are supported by API Management are supported or can be supported by Mobile Services or the Assistant. The API services that are exposed via the API Business Hub or Developer Portal use the HTTPS protocol, which limits the available authentication choices in the connection dialog to these options:

    • No authentication
    • Basic authentication
    • Single sign-on SSO

    However, a service might use an authentication method other than those listed that makes the Assistant unable to connect to the service due to not supporting that given method.

    Note

    SSO is supported only if SAML authentication is used and the identity provider is the same that is used by Mobile Services, API Management, and the back end.

  • Reuse of existing destinations – If an API is chosen from an API catalog API Business Hub or a Developer Portal, its connection details, including the following, can be reconfigured in the Assistant until the Finish option is selected:

    • Whether the URL is a sandbox or production URL
    • API key and the method used to obtain the API key
    • Template URLs of the selected API and the possible values for URL template parameters

    However, once the API's connection details and the destination are created on the server when it is reused from the Assistant, you can only enter the URL manually, since no configuration UI is available. The reason for this behavior is that the API product and artifact details are not saved on the Mobile Services side with the destination, therefore, when reusing the destination it is not known to the Assistant where the URL originated.

Consuming APIs From the SAP API Business Hub

Add an OData destination to your app from the SAP API Business Hub.

A mobile services account is not required to browse API products, their exposed APIs, and API documentation online. However, a mobile services account is required when consuming APIs. An additional third-party account may be required when consuming a non-SAP API via the API Business Hub.

If you select a scenario that includes a destination that consumes an API from the Business Hub, you are guided to add the product and API:

  1. Developer Portal – SAP API Business Hub

  2. API Product – Select the API product that exposes OData services.

  3. Artifact – Select the API to be used in the application.

  4. API Details – Includes:

    Service to Use - Specify whether to use the sandbox or production version. Not all APIs are available in both sandbox and production versions.

    Service URL - Additional information may be required when using the production version to be able to access the service driving the selected API, including, but not restricted to:

    • A production service may define more than one service URL, in which case you must carefully select the URL to be used by the mobile application.
    • A production URL may be incomplete, meaning the production URL may contain "gaps," such as template URL parameters that must be filled in manually. Some parameters are free text and some parameters might define a list of values to choose from. You must define the correct values to get a working production version from the URL.

    • API Key

      • Sandbox case: All sandbox versions of the services driving the APIs require an API key. This API key is automatically retrieved by the Assistant, and cannot be entered manually. The fetched key is saved with the destination created on the Mobile Services server, allowing the reuse of the newly created destination in other mobile applications.
      • Production case: The publisher of the API determines whether or not the API key is required. If required, a valid production key must be supplied manually by the user from the URL configuration screen, since it cannot automatically be retrieved.

        See Verify API Key for additional information.

  5. Destination Details – includes:

    • Name – name of the back-end endpoint, which is automatically filled in for the destination.
    • Back-end URL – the OData endpoint URL.
    • Proxy Type – On Premise or Internet.
    • URL Rewrite Mode – can be configured to determine where to rewrite the URL.
    • Maximum Connections – the number of allowed parallel connections.
    • Authentication Type – the authentication type used between the mobile service and the OData endpoint.

      Note

      If the scheme of the URL is https, the proxy type of the destination must be Internet. The Assistant recognizes such URLs of APIs consumed from the API Business Hub and sets this proxy type by default.

Important Notes
  • Ensure the destination is configured properly, including proxy type, authentication method, and credentials are set for production URLs, the correct API key is supplied if needed, and so on, so that the service can be accessed via the configured destination. Otherwise, the application won't be generated.
  • Project generation can take as long as 30 minutes, depending on the size of the service driving the selected API.
  • Sandbox versions of the OData services support only HTTP GET requests. Data modification create, update, delete, upsert requests are not allowed.
  • The SAP Cloud Platform SDK for iOS, including the Assistant, is not responsible for the OData services, their functionality, or availability of the APIs published via the API Business Hub. For service issues, contact the owners of the API products or open an incident using the component of the API product.
  • Some APIs are available in only sandbox or production version.
  • Sandbox services require no authentication. The Assistant sets the authentication type to No authentication automatically when consuming sandbox services.

Consuming APIs From a Developer Portal

Add an OData destination to your app from the Developer Portal.

  • Add the Developer Portal account using the Assistant. In contrast to the API Business Hub, there can be numerous Developer Portal instances exposing APIs. Therefore, to be able to consume a service from someone else's Developer Portal, that Developer Portal account must be added to the Assistant.
  • Add the SAP Cloud Platform user as a registered user with at least the Developer role to be able to list and consume services from the given Developer Portal. See Assign Users to Roles for details.

If you select a scenario that consumes an API from a Developer Portal, you are directed to add the service/product and API:

  1. Developer Portal – Developer Portal account

  2. API Product – Select the API product that exposes OData services.

  3. Artifact – Select the API to be used in the application.

  4. API and Destination Details – Select the service URL and the appropriate API key option.

    Note

    If the scheme of the URL is https, the proxy type of the destination must be Internet.

    Ensure the destination is configured properly, including proxy type, authentication method and credentials are set for production URLs, the correct API key is supplied if needed, and so on, so that the service can be accessed via the configured destination. Otherwise, the application won't generate.

    Note

    Trial accounts

    The following limitations apply to Developer Portal instances running on a trial Mobile Services account:

    • API keys can be obtained automatically only if the user account used to consume an API is the same that is used to run the Developer Portal service on an SAP Cloud Platform tenant. For example, if user X wants to consume an API from user Y's trial account, the API key cannot be fetched. The Assistant displays a warning message to each destination to a service that is exposed by a Developer Portal running under a trial account when generating the mobile application, but allows the user to choose to continue by using a null key. The API is usable in the generated app if the check API key policy isn't applied to the service on the given Developer Portal.

    • If an API key is required to access a service on a Developer Portal running under a trial account, the owner of the trial account can share his or her own key with the developers of the mobile application. We recommended this only when your are prototyping an app and the owner of the account is a member of the development team. In this case, the API key must be entered manually on the URL configuration screen.

    • A Developer Portal application can be created and/or the selected API can only be subscribed to an existing Developer Portal application by the Assistant if the user account that consumes the API is the same account that runs the Developer Portal service on an SAP Cloud Platform tenant. The Assistant displays a warning message for each destination to a service that is exposed by a Developer Portal running under a trial account when generating the mobile application.

    API keys

    The Assistant administers Developer Portal instances so that consumed services can be accessed by the generated mobile application. This administration also includes the handling of API keys. The developer specifies whether the API key should be fetched automatically for the given application or if it is to be supplied manually. The default option is to obtain the key automatically, however a key can be supplied manually if necessary.

    Additional

    • There are no sandbox APIs exposed via Developer Portals. Even if the service driving the API is a demo service, it appears as a production version.
    • There are no template service URLs exposed, only final ones.

Mac Catalyst Support

You can use Mac Catalyst support to create a Mac version of your iPhone or iPad app. To learn more about XCFrameworks and Mac Catalyst support, click here.

Create a New App for Mac Catalyst

  1. The SAP Cloud Platform SDK for iOS Assistant adds Mac Catalyst support during project creation. To enable support for Mac Catalyst in the newly generated application, select the Mac Catalyst checkbox and click Finish.

    The Assistant performs the following steps during project generation:

    1. All the SDK frameworks used by the app are in the .XCFramework format.
    2. The app target is enabled to run additionally on Mac.
    3. A build script that signs the embedded SDK frameworks with your signing certificate has been added to the Build Phases. The build script is located at ./scripts/codesign.py.
  2. Launch the application on Mac by selecting My Mac as the destination and clicking Run.

Before the app can run on a Mac, certain prerequisites need to be fulfilled:

  • For Apps with Automatic Signing

    a. Add the keychain sharing capability: This is to enable the read/write to the Mac system keychain. No actual sharing is required or expected, only the rights to access the keychain as on iOS devices. In Xcode 11.3.1, adding the keychain sharing capability is not sufficient in Xcode 11.3.1. An app group also needs to be added:

    1. Add an App Group Capability from the Signing & Capabilities Section using Capability tab.
    2. Create an App Group Identifier under Signing & CapabilitiesApp Groups
    3. Verify that Provisioning Profile is set to Xcode Managed Profile.

    b. Specify a Signing Certificate: Adding the App Group will also trigger the signing certificate selection procedure.

  • For Apps with Manual Signing

    Add a macOS Provisioning Profile:

    1. Go to your Apple Developer Account Page.

    2. Go to Certificates, Identifiers & ProfilesIdentifiers.

    3. Select the app id of your project.

    4. Edit the app id configurations. Search for Capability with the name "Mac Catalyst".

    5. Enable Mac Catalyst, Configure the Mac Catalyst Capability and choose Automatically create an identifier. Save changes.

    6. Create a macOS provisioning profile with this app id. Download and import this provisioning profile.

    7. Verify that provisioning Profile is set correctly.

    The signing certificate is selected as part of the provisioning profile generation step.

    In case multiple certificates are found in your keychain for Apple Development identity:

    1. Create a user-defined build setting in Xcode with the name DEVELOPER_SIGNING_CERTIFICATE.

    2. Enter the value of the setting DEVELOPER_SIGNING_CERTIFICATE with the Common Name of the certificate. If the Common Name isn't unique, use SHA-1 fingerprint.

    3. If using Common Name, go to your Keychain Accesslogin. Select the required certificate and Get Info. Copy the Common Name value.

    4. If using SHA-1 Fingerprint, go to your Keychain Accesslogin. Select the required certificate and Get Info. Copy the SHA-1 fingerprint value.

    5. Paste this copied value to the build setting DEVELOPER_SIGNING_CERTIFICATE created above.

Enable Mac Catalyst Support on an Existing iPhone or iPad App

You can use Mac Catalyst support to update existing iPhone or iPad apps to run on a Mac.

  1. Enable the app target to run on Mac.
  2. Create a code signing script - Export the Code Signing Script using the Assistant's Export Code Signing Script feature.

Assistant Features

Importing and Managing Xcode Projects

Manage Xcode projects directly from the Assistant:

Importing an Xcode Project

From the Assistant launch screen, click Import project.

Note

Import project only imports Xcode projects that have been created by the Assistant.

Managing Xcode Projects

  1. The Assistant lists recent Xcode projects.
  2. Right-click the project of interest and select either: Open to open the project in Xcode, Show in Finder, Configure in Mobile Services opens the app in the mobile services cockpit,Remove from list, or Delete.
  3. You can also click Create new to create a new Xcode project.

Managing Projects

Select All Projects from the Assistant screen to manage them from the Projects screen. For a selected project you can:

Regenerate Proxy Classes

Regenerates the proxy classes based on the current back-end metadata. The Assistant attempts to download the new metadata from Mobile Services and regenerate the proxy classes based on the new metadata. The old proxy classes are moved into an archive folder on your disk. If no metadata is present, the Assistant does not regenerate or attempt to download them from Mobile Services.

Note

After clicking to regenerate proxies, the Assistant compares the current cloud destinations with the destinations originally used to generate proxies and displays a warning to notify the developer if there has been a change in the proxy definition that could adversely affect the app. The developer can Continue or Cancel regeneration. Regeneration is always based on the current cloud destination configuration.

Refresh Frameworks

Refresh the referenced Swift frameworks for an existing project. This allows you, for example, to upgrade to newer SDK frameworks when they become available. When you refresh, the frameworks you replace are saved to a Frameworks_OLD folder under the generated project's folder, which lets you switch back to previous framework versions. Additionally, the proxy classes are regenerated based on the locally stored metadata originally used to generate the proxy classes. This ensures that the proxy classes remain compatible with the latest SDK frameworks. Upgrade any apps managed in the Assistant by clicking the project name, then selecting Refresh Frameworks button.

Add Translation

See Localizing iOS Apps for details.

Manage Xcode Projects in GitHub

Manage Xcode projects in GitHub or other source code management systems, without being required to add the SAP Cloud Platform SDK for iOS frameworks into the repository that may be problematic due to their size and static nature. Instead, easily add frameworks to projects that have been freshly cloned to disk.

  1. Import projects and recognize if the project lacks the framework files. If so, the Assistant prompts you to add the frameworks and adds the current version of the frameworks to the project.
  2. Automatically open Xcode on imported projects after a successful import. This is enabled by default, but can be disabled in Preferences by deselecting Automatically open imported project in Xcode.
  3. A .gitignore file is included to generated apps that excludes the framework files and other general Xcode files that usually are not pushed to GitHub.
  4. Register for the .xcodeproj file extension so developers can right-click and select Open withAssistant, to trigger the import and add frameworks flow easily using Finder.
  5. A shell script is added to generated apps and is part of the build configuration that checks if the frameworks are missing in the build phase, and then copies the frameworks from the Assistant and the script checks an environment variable and defaults to /Applications for the Assistant location, which is useful on build machines. See Build Phase Script for details.

Install OData Tools

Install Troubleshooting with ILOData and Proxy Classes into your /usr/local/bin directory so that you can easily use these OData tools from the Terminal. To install the tools to a custom location, hold down the Command (⌘) key and select SAP Cloud Platform SDK for iOS AssistantInstall Tools.

Export Frameworks

Create a local copy of all SDK frameworks. Open the Assistant main menu and select Export Frameworks to extract the new frameworks locally so you can copy them into any Xcode project not managed by the Assistant. Follow the prompts to copy the frameworks to your local disk.

Preferences

You can set any of these general Assistant settings from the SAP Cloud Platform SDK for iOS AssistantPreferences menu

Project Navigation

  • Navigation – Automatically open new projects, and imported projects, in Xcode.

View Assistant Logs

  • Copy the filter – Copy the subsystem:com.sap.SAPCPSDKforiOSAssistant filter and use it to limit console display to Assistant-related activities.
  • Open Console – View Assistant-related logs in the Console.app, which can be useful for debugging.

Help

Access the Mentor application, API Documentation, and report an issue from the Help menu.


Last update: December 3, 2020