iOS Integration Guide

Implement donation functionality into your app

Ahillz iOS SDK provides powerful and customizable way for developers to become responsible companies. By following a simple guide laid out below, you can implement and set-up Ahillz SDK in minutes.

Ahillz ShowRoom app was developed to demonstrate all the possible ways of using and presenting Ahillz inside any third-party apps. Please submit your email to get access to Ahillz ShowRoom.

Install and configure the SDK

Before you can start using Ahillz within your app, you'll need to download Ahillz framework and import it into your target project properly. Please let us know by emailing [email protected] or by submitting your email, and we'll be right back with the download link and your personal Public and Secret keys to be used during the Ahillz initialization.

Assuming you've received the Ahillz framework along with a personal key pair from us already, you can start integrating the SDK into your own app.

  1. Install the latest version of Xcode.
  2. Import Ahillz framework by dragging an Ahillz.xcodeproj file right into your app as shown below.
  3. Make sure that Ahillz.framework is listed in the Frameworks, Libraries, and Embedded Content section on the General tab of your app's target settings. It should be marked as Embed & Sign.
  4. Make sure that there is no circular frameworks dependency by going into Ahillz framework target settings and ensuring that Frameworks and Libraries section is empty.
  5. Import Ahillz to make it visible by your code.

    For Swift, simply use the line below in each .swift file that requires access to Ahillz.

    import UIKit
    import Ahillz

    For Objective-C, import the header specified below in each .m file that requires access to Ahillz. Please note that this header file is generated automatically by Xcode when you are importing a Swift framework (Ahillz) into your project.

    #import "AppDelegate.h"
    #import <Ahillz/Ahillz-Swift.h>

    You may also need to include Swift classes and protocols in your Objective-C headers (may not be required): @class Ahillz; @protocol AhillzDelegate;

  6. Clean the build folder and build the app.
  7. If you are having issues implementing Ahillz framework in your app and making it visible to your code, please refer to the frameworks-related guides available online, keeping in mind that Ahillz was written in Swift.

Configure Ahillz during your app launch

Before you can start presenting Ahillz donations screens to your users, you need to initialize Ahillz with your personal key pair. Please contact us at [email protected] to get your keys for free. The initialization should happen immediately after your app launches, so we recommend doing it in your AppDelegate file.

import UIKit
import Ahillz

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    Ahillz.initWithAppKey("demo_app_key", secretKey:"demo_secret_key", appTitle:"YourAppTitle")
    return true
  }

}

Optionally, provide your app's URL after initialing Ahillz — this would enable users to include a link pointing to your app when and if sharing some charitable cause.

Ahillz.setMyAppURL(URL(string: "https://www.ahillz.com")!)

Additionally, we recommend notifying Ahillz when your app enters background and/or is going to terminate by using the methods below:

func applicationDidEnterBackground(_ application: UIApplication) {
  Ahillz.appDidEnterBackground()
}

func applicationWillTerminate(_ application: UIApplication) {
  Ahillz.appWillTerminate()
}

Present Ahillz

Users will be able to explore charitable causes and donate to them after you present a custom Ahillz View Controller to the users. There are multiple ways of prompting a user to open Ahillz, and the ideal result of all of them is a presentation of Ahillz View Controller.

We recommend that you place a custom button suggesting a user to support charitable causes in a prominent place in your app, and present Ahillz to the user once this button is clicked.

import UIKit
import Ahillz

  class ViewController: UIViewController {

    @IBAction func customButtonPressed(sender:UIButton) {
      Ahillz.presentAhillzWithRootViewController(self)
    }

}

This would result in a presentation of Ahillz View Controller. Nothing else is required from your side; a user will close Ahillz once he/she is done.

Ahillz Ads

Ahillz supports several types of in-app advertisements that you can show to your users. Almost all of them contain a call-to-action button, which presents Ahillz View Controller when clicked. See below the list of available ads and how to present them.

Interstitial ad

This is the most convenient advertisement style. We recommend to present it when user is switching between screens or view controllers in your app, or after a user finishes playing a game level.

Present the ad by executing the command below:

Ahillz.presentAhillzInterstitialAd(with: self)

Prior to presenting the ad, you may want to check if the ad has already been loaded by calling the following Ahillz method:

let interstitialAdAvailable = Ahillz.isInterstitialAdLoaded()

Ahillz interstitial ads come in different shapes and sizes; the ad you'll present may be one of the following:

Banner ad

This is the most compact advertisement style (though least performing). We recommend placing and keeping it in a permanent highly-visible position in your app. When the banner is clicked, Ahillz View Controller will be presented to the user automatically.

After asking Ahillz to present a banner ad, you will receive a banner ad object that you'll need to add to your custom view and position appropriately. The positioning part can be done either via constraints or via frames. Below is the example of presenting an Ahillz banner ad and positioning it via constraints:

Ahillz.presentAhillzBannerAd(with: self) {
  (adView:AhillzBannerAdView) in

  //Ahillz has a recommended banner size, but you can always use your own size
  let bannerSize = adView.getRecommendedBannerSize()
  self.view.addSubview(adView)

  //When set to true, banner is removed from superview automatically when tapped by user
  adView.shouldRemoveFromSuperviewWhenClicked = true

  //Adding constraints
  adView.widthAnchor.constraint(equalToConstant: bannerSize.width).isActive = true
  adView.heightAnchor.constraint(equalToConstant: bannerSize.height).isActive = true
  adView.centerXAnchor.constraint(equalTo: self.view.centerXAnchor).isActive = true
  adView.bottomAnchor.constraint(equalTo: self.view.bottomAnchor, constant: -20).isActive = true

  //Layouting new constraints
  self.view.layoutIfNeeded()

}

Below is the example of how you can position Ahillz banner ad via frames:

Ahillz.presentAhillzBannerAd(with: self) {
  (adView:AhillzBannerAdView) in

  //Ahillz has a recommended banner size, but you can always use your own size
  let bannerSize = adView.getRecommendedBannerSize()
  self.view.addSubview(adView)

  //When set to true, banner is removed from superview automatically when tapped by user
  adView.shouldRemoveFromSuperviewWhenClicked = true

  //Setting banner frame
  adView.setBannerFrame(CGRect(x: 50, y: 50, width: bannerSize.width, height: bannerSize.height))

  //Set to true because we are using frames not constraints
  adView.translatesAutoresizingMaskIntoConstraints = true

}

Prior to presenting the ad, you may want to check if the ad has already been loaded by calling the following Ahillz method:

let bannerAdAvailable = Ahillz.isBannerAdLoaded()

Native ad

This is the most flexible advertisement style. You are free to decide the way and form in which you want to present the ad to the user. This can be a table cell, a collection cell, a custom view or a popup, etc.

You can check whether the native ad has been loaded and retrieve it by calling:

let nativeAdAvailable = Ahillz.isNativeAdLoaded()
let nativeAd = Ahillz.getNativeCauseAd()

The cause field of the native ad object contains charitable cause information (such as title, location, number of donors, how much funds been raised so far, and much more). You are free to present this information in whichever way you want. We will demonstrate the presentation of a fraction of available information in a console output.

if let cause = nativeAd.cause {

  let causeTitle = cause.causeTitle
  let causeLocation = cause.locationShort

  print("Cause title is \(causeTitle)")

  //The cause may or may not have an associated targetCauseId, which you can provide
  //when presenting Ahillz to make it open a specific cause page
  let targetCauseId = nativeAd?.targetCauseId

  //Let Ahillz know that the user has viewed the native ad
  Ahillz.didDisplayAhillzNativeAd(nativeAd)

}

<...>

//When your custom button is pressed, you should present Ahillz
@IBAction func openCausePressed(sender:UIButton) {
  Ahillz.presentAhillzWithRootViewController(self, causeId: targetCauseId)
  Ahillz.didClickAhillzNativeAd(ad)
}

Note that it is highly recommended to notify Ahillz of actions that a user takes with the native ad (when the ad is clicked and displayed).

Ahillz Button

We suggest that you inititalize an Ahillz Button and install it in a permanent place of your application. That would allow your users to remember the way they could access Ahillz and form a better association between your brand and charitable causes of their choice. Refer to the code below to see how a button can be created and installed in the UIView:

func presentAhillzButton() {

  let ahillz_button = AhillzButton(rootViewController: self)

  //Creating button configuration. Can include button text, the color of shadow, foreground and background of the button
  let button_config:[AhillzButton.ButtonSetting] = [.buttonText(.auto)]
  ahillz_button.configureButtonWithSettings(button_config)

  //Set real button size. The button width would impact the way the button is presented. This is mandatory
  ahillz_button.setButtonSize(CGSize(width: 300, height: 50))
  ahillz_button.renderButton() //this is required

  ahillz_button.frame = CGRect(x: 50, y: 50, width: 300, height: 50))
  ahillz_button.translatesAutoresizingMaskIntoConstraints = true

  self.view.addSubview(ahillz_button)
}

Please note that the presentation of the Ahillz Button depends significantly on the size of the button, which you must specify before rendering it. Button's width is what plays a defining role. If the width is 70 points or less, only Ahillz logo would be visible. If the width is from 70 points to 150 points — only call-to-action text would be visible. Otherwise, if the width is greater than 150 points, the full style would be applied, with Ahillz logo and call-to-action text.

Ahillz Delegate

Ahillz delegate provides an easy way for your class to listen to certain updates happening on Ahillz side. Below are some of them:

import UIKit
import Ahillz

class ViewController: UIViewController {

    override func viewDidLoad() {
      super.viewDidLoad()
      Ahillz.setDelegate(self)
    }

}

extension ViewController {

  //This method is called when an ad of a specific type has been loaded
  //and is ready to be presented
  func ahillzAdLoadedWithType(_ adType: AhillzAdType) {
    print("AHILLZ DELEGATE: Ahillz ad loaded")
  }

  //This method is called when a native ad has been loaded
  //and is ready to be presented
  func ahillzNativeAdLoaded(_ nativeAd: AhillzNativeAd) {
    print("AHILLZ DELEGATE: Ahillz native ad loaded")
  }

  func ahillzDidPresent() {
    print("AHILLZ DELEGATE: Ahillz was presented")
  }

  func ahillzDidClose() {
    print("AHILLZ DELEGATE: User has just closed Ahillz")
  }

}

Restrictions

The current version of Ahillz is only designed to work on iPhones. Only vertical device orientation is supported. You won't be able to present Ahillz View Controller to user on any device but iPhone.

Even though it would be possible for almost all of your global users to donate to charities via Ahillz, the current version of the SDK and backend was predominantly designed to support North American donors. That is why we recommend presenting Ahillz only to users coming from USA and Canada mainly for legal reasons. In the future we will lift this restriction.

Ahillz best practices

We recommend presenting Ahillz ads to as many eligible users as possible. The most convenient way of letting your users know about Ahillz existence is displaying Ahillz Interstitial ad and allowing the user to explore Ahillz further if she is interested.

We strongly recommend to emphasize the partnership between your app and Ahillz prominently, and create a permanent button accessible from the settings screen of your app that would present Ahillz when clicked. It would also help to educate the user about the location of this button.

Testing

We are using Stripe to process the donations. You can use the following test cards (suggested by Stripe) to test the donation process:

4242 4242 4242 4242
EXP: 02/22 CVC: 123
4000 0000 0000 0002
EXP: 02/22 CVC: 123

Enable Apple Pay donations

Apple Pay simplifies donation process, and will make your users enjoy giving via your app. Note, that enabling Apple Pay is not mandatory; your users will be able to donate by simply entering their card information. However, we recommend activating Apple Pay as this would substantially improve user experience.

Please follow steps listed below to enable your users to give via Apple Pay.

Step 1: Register for an Apple Merchant ID

First, you’ll need to obtain an Apple Merchant ID. Start by heading to the Registering a Merchant ID page on the Apple Developer website.

Fill out the form with a description and identifier. Your description is for your own records and can be modified in the future (we recommend just using the name of your app). The identifier must be unique (across all apps, not just yours) and can’t be changed later (although you can always make another one). We recommend using merchant.com.{{your_app_name}}. Save this value for later use when developing your app.

Step 2: Create a new Apple Pay certificate

You need to include a certificate in your app to encrypt outgoing payment data. This involves 3 steps:

  1. Obtain a CSR (certificate signing request) file from Ahillz
  2. Use this CSR to generate a certificate through Apple
  3. Send the certificate back to us at Ahillz

First, contact us to receive your personal free .certSigningRequest file.

Next, back on the Apple Developer site, visit the Add iOS Certificate page. Choose Apple Pay Certificate from the options and click Continue. On the next page, choose the Merchant ID you created earlier from the dropdown and continue.

The next page explains that you can obtain a CSR from your Payment Provider (which at this point you’ve done already) or create one manually. Important note: you must use the CSR provided by us - creating your own won’t work. So ignore the directions at the bottom of this page and continue on.

You’ll be prompted to upload a .certSigningRequest file. Choose the file we have sent to you and continue. You’ll see a success page, with an option to download your certificate. Download it. Finally, send us this .cer file. We will share it with our payment processor (who is Stripe) to enable payments in your app.

Step 3: Integrate with Xcode

Add the Apple Pay capability to your app. In Xcode, open your project settings, choose the Capabilities tab, and enable the Apple Pay switch. You may be prompted to log in to your developer account at this point. Enable the checkbox next to the merchant ID you created earlier, and your app is ready to accept donations via Apple Pay.

See Ahillz in action

Download a demo app to give Ahillz a go. iOS devices only