Getting started

In this section, we will help you get started by going through the preliminary steps for a smooth integration:

  • Configure Push Notifications in your app and generate a certificate on the Apple developer portal
  • Set the Accengage dashboard correctly
  • Create URL Schemes for deep linking

During these steps, you will need to use Xcode, your Apple Developer account, as well as the Accengage Dashboard.

Requirements and important information on the iOS SDK

The Accengage iOS SDK is provided as a dynamic framework and is compatible with:

  • Xcode 12+
  • iOS 11+

In terms of size, the SDK will increase your app download size by ~608 Kb.

In order to integrate it, you will need:

  • A partner id and a private key for each application and each environment (development and production), available for registered customers on our platform. If you do not have a partner id and private key yet, please contact our support at http://ticket.accengage.com.

See below to set these correctly with your other credentials:

  • To generate a Push Notification certificate (see below)
  • The Bundle Id of your application which should be entered in the application form in the Accengage dashboard (Settings > Manage application > Edit).

Activate Push Notifications

Enable Push Notifications in Xcode

  1. In the project editor, choose a target and click Capabilities.
  2. In the Push Notifications section, click the switch to turn it from OFF to ON.

Generate and export an APNS client TLS certificate from the Apple developer portal

Generate an APNS client TLS certificate

You need to generate a separate client TLS certificate for each app you distribute that uses Push Notifications including Development and Production versions.

It is important that you generate a Development (Sandbox) Push Notification certificate to use with a Development Provisioning Profile, and/or a Production Push Notification certificate to use with an Ad Hoc or Distribution Provisioning Profile. They will be used in 2 separate applications within Accengage Dashboard (see below) and it will be important that you respect this differentiation.

Generating the certificate fully enables Push Notifications for the associated App ID. In your developer account, you will notice that the Push Notifications service for the App ID changes automatically from Configurable to Enabled.

  1. In your developer account, go to Certificates, Identifiers & Profiles and if necessary, choose the operating system from the pop-up menu on the left (for macOS apps, choose OS X).
  2. Under Certificates, select All.
  3. Click the Add button + in the upper-right corner.

Img

  1. Under Production, select the “Apple Push Notification service SSL (Sandbox & Production)” checkbox, then click Continue.

Img

  1. Choose an App ID from the App ID pop-up menu, and click Continue.
  2. Choose the explicit App ID that matches your bundle ID.
  3. Follow the instructions to create a certificate signing request on your Mac, and click Continue.
  4. Click Choose File.
  5. In the dialog that appears, select the certificate request file (a file with a .certSigningRequest file extension), and click Choose.
  6. Click Continue.
  7. Click Download and double-click the downloaded file (a file with a .cer file extension) to add the certificate to your keychain.
  8. Click Done.

Create a certificate signing request

  1. Launch Keychain Access located in /Applications/Utilities.
  2. Choose Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority.
  3. In the Certificate Assistant dialog, enter an email address in the User Email Address field.
  4. In the Common Name field, enter a name for the key (for example, Gita Kumar Dev Key).
  5. Leave the CA Email Address field empty.
  6. Choose “Saved to disk”, and click Continue.

Img

Export the client TLS identity from your Mac

Export the identity from the keychain on the Mac where you created it, and copy it to the appropriate place on the server that runs the provider code and connects with the development or production version of APNs.

  1. Launch Keychain Access.
  2. In the Category section, select My Certificates.
  3. Find the certificate you want to export and disclose its contents.

Img

  1. You’ll see both a certificate and a private key.
  2. Select both the certificate and the key, and choose File > Export Items.
  3. From the File Format pop-up menu, choose a file format that your server accepts.
  4. Enter a filename in the Save As field, and click Save.
  5. The certificate and key are saved to the location you specified as a text file in the Personal Information Exchange format (a file with a .p12 file extension).

Configure the Accengage dashboard for Push Notifications

Once you have exported your Push Notification certificate, you need to upload it in the Accengage Dashboard. Please go to Settings > Manage Application and click on the pencil to edit the configurations. You should have 2 separate applications, 1 for the Development environment, and 1 for Production. In the relevant application, you should:

  1. Upload the Push Notification certificate.
  2. Enter its password.
  3. Tick the right type of Push Notification certificate.
  4. Enter the right Bundle Id.

Once you have set this information up, you are now ready to integrate the SDK!

Deep Linking

Deep Linking is becoming very important, it's a great way to enhance the effectiveness of your app's marketing campaigns. It will allow you to open a specific view of your app from another app, from a push message, from an in-app message or even from a website to your app.

There are two common strategies for deep linking in iOS. For most applications, implementing the ACCDeepLinkDelegate will be the preferred strategy. This allows complete control over URL processing and sidesteps the need to register a unique URL scheme with the operating system. The alternative strategy is to register a unique URL scheme with the operating system and handle URL processing in the App Delegate’s openURL: callback.

Configure URL Schemes

Creating URL schemes

To take advantage of it, you must create a custom URL Scheme associated with your application. A URL scheme lets you communicate with other apps through a protocol that you define. To find out more, check out Apple documentation.

To register your URL Scheme:

  1. Select your app target from the sidebar, then select the Info tab.
  2. Open the URL Types expander and click +.
  3. In the URL Schemes field, enter your_app_url_scheme.
  4. Assign a unique identifier to the scheme to ensure uniqueness and avoid name collisions, so we’ll use com.myapp.url for the example.

Img

That’s it! To verify that everything works:

  1. Run your app
  2. Open Safari on the same device
  3. Type your_app_url_scheme:// in the address bar, then press Go
  4. You should arrive on the expected page

Whitelisting URL Schemes

iOS 9 introduces changes that impact URL scheme management. For more details, you can consult Apple's documentation.

Make sure that your application Info.plist includes the LSApplicationQueriesSchemes set with your app's URL Scheme (see previous section to find out how to create your app's URL scheme) and every scheme your app will query.

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>your_app_url_scheme</string>
    <string>other_app</string>
</array>

Deep linking is most easily accomplished by implementing the deep link delegate’s receivedDeepLink:completionHandler: callback. This allow your app to process the URL provided in a ACCDeepLinkAction and use it to navigate to the desired view within your app.

- (void)receivedDeepLink:(nonnull NSURL *)url completionHandler:(void (^ _Nonnull)(BOOL success))completionHandler {
    NSArray *pathComponents = url.pathComponents;
    
    if ([pathComponents containsObject:ViewStoryboardID]) {
        // Navigate to desired view
        completionHandler(true);
        return;
    }
   completionHandler(false); 
}