iOS

Cocoapods


The Upsight SDK and mediation library can be installed via cocoapods. To do so, simply add pod 'UpsightKit', '~> 4.2' and pod 'UpsightAdMediation', '~> 2.6' similar to the following in your Podfile:

target 'MyApp' do
  pod 'UpsightKit', '~> 4.2'
  pod 'UpsightAdMediation', '~> 2.6'
end

Then run a pod install inside your terminal, or from CocoaPods.app.

You can read more about our cocoapod on the UpsightKit page.

Manual Integration


Download the SDK

To begin, download the latest Upsight SDK.

Complete the following steps to integrate the base SDK and the ad mediation module:

  1. From the Upsight SDK folder, drag UpsightKit.framework into your Project’s Framework folder in the Xcode Navigator window. Ensure that UpsightKit.framework was added to the Build Phases section of the target settings. Then add CoreTelephony.framework and AdSupport.framework provided by Apple to the Build Phases section. Integration step 1

  2. Navigate to the 'Info' page of the project settings. Under 'Custom iOS Target Properties' create a key called UpsightAppToken with String as a Type and copy your Upsight App Token to the value field. Next create a key called UpsightPublicKey with String as a Type and copy your App Public Key as a string to the value field. These are provided on the Upsight dashboard under Settings > Applications > App Name. Integration step 2

  3. In the Build Settings section of the target, add -ObjC to the Other Linker Flags field. Integration step 3

    Note -ObjC tag is case sensitive.

  4. Download the Upsight Ad Mediation library.

  5. Import the Upsight Ad Mediation SDK into your project. Right Click YourProject > Add Files to "YourProject".

  6. Next browse to the location where you have uncompressed the SDK and select UpsightAdMediationSDK, on the same dialog, choose "Create groups". Now click "Add".

Once finished, your project should contain four additional files:

UpsightAdMediation.h
UpsightAdMediationDefinitions.h
libUpsightMediation.a
libUpsightMediationAds.a

Project Configuration

Required Frameworks

The Upsight Ad Mediation SDK requires these frameworks to be included in addition to the base frameworks required by the Upsight SDK:

  1. Accelerate.framework
  2. AudioToolbox.framework
  3. AVFoundation.framework
  4. CoreGraphics.framework
  5. CoreLocation.framework
  6. CoreMedia.framework
  7. EventKit.framework
  8. EventKitUI.framework
  9. Foundation.framework
  10. GameKit.framework
  11. iAd.framework
  12. libsqlite3.dylib
  13. libxml2.dylib
  14. libz.dylib
  15. MediaPlayer.framework
  16. MessageUI.framework
  17. MobileCoreServices.framework
  18. QuartzCore.framework
  19. Social.framework (weak link)
  20. StoreKit.framework
  21. SystemConfiguration.framework
  22. Twitter.framework
  23. UIKit.framework
  24. WebKit.framework

Disabling ATS and BitCode

AppTransportSecurity

Some of the ad network SDKs used by the Upsight Ad Mediation SDK do not support sending their data over HTTPS. If you are building on XCode 7, you must turn off App Transport Security by adding an additional dictionary item to your Info.plist. To so, add a dictionary item in your Info.plist called NSAppTransportSecurity with a boolean item NSAllowsArbitraryLoads set to YES. You can view more information this specific setting on Apple's documentation website.

BitCode

While the Upsight and UpsightAdMediation SDK are built with bitcode enabled, some of the included ad network libraries have not yet enabled bitcode. You can manually disable bitcode in your application by going to the Build Options in your target's build settings and setting Enable Bitcode to No.

Tracking Paying Users


Tracking Paying Users

Upsight offers you the ability to track in-app purchase events, which not only provides you with revenue data in your dashboards, but also allows you to segment your users based on their spending behaviours.

There are two separate methods that you can use to track monetization. If you wish to track a purchase made through the App Store, use the following method from the Upsight class:

 + (void)recordInAppPurchaseEventWithResolution:(USPurchaseResolution)resolution
 product:(NSString *)product
 quantity:(NSUInteger)quantity
 price:(float)price
 currency:(NSString *)currency
 transactionIdentifier:(NSString *)transactionIdentifier;
  • resolution - one of:

    • USPurchaseResolutionBuy if the purchase was successful.
    • USPurchaseResolutionCancel if the user canceled the purchase.
  • product - The product name, as provided by the productIdentifier property of an SKProduct object.

  • quantity - The number of products purchased during the transaction, as set in the quantity property of an SKPayment object.

  • price - the value returned by price.floatValue where price is the price property of an SKProduct object.

  • currency - the value returned by [priceLocale objectForKey:NSLocaleCurrencyCode] where priceLocale is the priceLocale of an SKProduct object.

  • transactionIdentifier - A value extracted from the SKTransaction object sent by Apple during the StoreKit exchange.

When the SDK sends an InAppPurchase event recorded with this method, it attaches the receipt object from the transaction with the App Store. The Upsight server then validates this receipt with the Apple servers.

If you have a purchase to record that did not involve the Apple store, you can use this method instead:

+ (void)recordMonetizationEventWithTotalPrice:(float)totalPrice currency:
(NSString *)currency;
  • totalPrice - the total amount of the transaction.

  • currency - typically retrieved using [[NSLocale currentLocale] objectForKey:NSLocaleCurrencyCode].

Showing Mediated Video Ads


Milestones

Milestones track user movement through your app and allow you to manage exactly when and where a user sees content, including mediated ads. Milestones are triggered when your user reaches a point in your application that you want to track or take action on. After a user hits a Milestone of a given scope, the user will be able to see content from an open Billboard that also has that same scope.

To set a milestone, simply call the following function and assign a scope:

[Upsight recordMilestoneEventForScope:@"main_menu"];

Milestones have one required property - a "Scope" that uniquely describes that location in your application. Examples of Scope are "main_menu", "inventory", or "level_up". Additionally Milestone can track event properties by using a NSDictionary:

[Upsight recordMilestoneEventForScope:@"main_menu" properties:@{ @"Age": @"42", @"Gender": @"Male"}];


Important Milestones must also be setup in the Upsight dashboard. See Dashboard Setup for instructions.

Billboards

In order to display marketing content, a 'Billboard' must exist and be open. A billboard is like an empty frame into which the SDK can place content it receives from the server as a response to a milestone call. Like milestone events, each billboard is associated with a Scope. The content returned after a Milestone event will have the same Scope as the Milestone.

There are three basic steps to show content:

  1. Add the USBillboardDelegate protocol to one of your classes and implement presentingViewControllerForBillboard:
  2. Record a Milestone event for the scope.
  3. Get the USBillboard instance for the scope in which you want to show content, and set its delegate property to point at an instance of the class from step 1.

Important By changing when your code starts performing steps 2 and 3 above, you can control when your content will be shown. Steps 2 and 3 do not need to be performed in a particular order, and content won't be shown until both steps have been performed. This allows you to control content freely. Additionally, you can use the isContentReady method to check that content was delivered for a given milestone and is ready for display before even opening up a billboard.

[Upsight billboardForScope:scope].isContentReady;

Rewarded Video Ads - Handling Rewards

In the event your user receives a reward, you are notified through this optional method of the billboard delegate protocol:

- (void)billboard:(id<USBillboard>)aBillboard didReceiveReward:
(id<USReward>)aReward;

Validating Rewards

If you would like to validate the reward that the Upsight server has granted to the device, you can do so by sending reward signature data to your server and performing an operation on the contents. You can get the signature data which is stored as a JSON NSData object by calling aReward.signatureData.

This JSON object contains the product, sid, quantity, nonce, and signature of the reward. You use the product, sid, quantity, and nonce along with your app's secret_key to produce the signature provided in the payload on your server.

Below is a python example of reward verification:

import base64
import hashlib
import hmac


def validate_signature_data(signature_data, secret):
    """Validates the signature for Upsight rewards.

    >>> secret = 'YOUR_32_CHAR_SECRET_KEY'
    >>> signature_data = {
    ...     'idfv': 'AAAAAAAA-0000-0000-0000-000000000000',
    ...     'nonce': '0437121572:rambo_cat:1',
    ...     'product': 'rambo_cat',
    ...     'quantity': 1,
    ...     'sid': '10000000000000000000',
    ...     'sig4': 'joQiupsyEe10Ui83TCPuScVBfOo',
    ...     'token': 'YOUR_APP_TOKEN'
    ... }
    >>> validate_signature_data(signature_data, secret)

    If the signature is invalid, or there is a problem with the signature_data
    dictionary, ValueError will be raised:

    >>> signature_data['sig4'] = 'invalid'
    >>> validate_signature_data(signature_data, secret)
    Traceback (most recent call last):
      ...
    ValueError: incorrect signature

    :param dict signature_data: A dictionary of signature data, from the SDK.
    :param str secret: Your app secret string.
    :raises ValueError: if the signature is invalid.
    """
    for required in ('nonce', 'sig4', 'token'):
        if required not in signature_data:
            raise ValueError('signature_data is missing {}'.format(required))

    identifiers = {}
    for identifier in ('device', 'gid', 'ifa', 'mac', 'odid', 'odin',
                       'idfv', 'sid'):
        value = signature_data.get(identifier)
        if not value:
            continue
        if isinstance(value, unicode):
            value = value.encode('utf8')
        identifiers[identifier] = value
    if not identifiers:
        raise ValueError('signature_data is missing identifiers')

    message = ':'.join((':'.join(str(identifiers[key])
                                 for key in sorted(identifiers.keys())),
                        signature_data['token'],
                        signature_data['nonce']))
    signature_hash = hmac.new(str(secret), message, hashlib.sha1)
    signature = base64.urlsafe_b64encode(signature_hash.digest()).rstrip('=')
    if not hmac.compare_digest(signature_data['sig4'], signature):
        raise ValueError('incorrect signature')

Dashboard Setup

In order to trigger ads in your app, you'll need to add milestones and rewards to your application settings in the Upsight dashboard, and create static interstitial, non-rewarded video, or rewarded video campaigns. See the Dashboard Setup section for details.