Skip to content

Integration Instructions

System Requirements:

Unity

The Itavio Unity plugin requires Unity 5.0.1 or greater.

Android

The ItavioSdk requires a minimum Android API level 16.

iOS

The ItavioSdk requires iOS Sdk 8 or greater. Up to date Xcode is recommended.

To integrate ItavioSdk into your Unity application:

Step 1 - Import the UnityPackage

(1) From the menu Assets > Import Package > Custom Package... (2) Select the ItavioUnityPlugin.unitypackage, Open then Import.

Step 2 - Define Platforms

(1) Select /Assets/Plugins/Itavio/Resources/itavioConfig (2) In the Inspector, add a new platform, name it and fill out the values for the desired environment with the Itavio provided secret key id and secret key.

Step 3 - Initialize Itavio

(1) Add this directive to the MonoBehaviour that will be making calls to the ItavioManager:

using itavio;

(2) In the Start method call itavioManager.initialize(PLATFORM_NAME) with the name of the target platform defined in the itavioConfig file.

void Start()
{
    itavioManager.initialize(PLATFORM_NAME);
}

Step 4 - Using Itavio

Be sure that itavioManager has been initialized before calling any of these methods.

Directives

(1) Use the itavio directive

using itavio;

Linking to the Itavio Parent App (iOS Only)

(1) To link with the Parent App use

#if UNITY_IOS
itavioManager.linkWithParentApp(SHOW_GET_APP_DIALOG);
#endif

To re-link with the Parent App use

#if UNITY_IOS
itavioManager.linkWithParentApp(SHOW_GET_APP_DIALOG, true);
#endif

if SHOW_GET_APP_DIALOG is true the user will be prompted to download the Parent App if it is not installed.

(2) The plugin will respond by firing the OnLinkWithParentApp event

void Start()
{
    #if UNITY_IOS
    itavioManager.OnLinkWithParentApp += itavioManager_OnLinkWithParentApp;
    #endif
}

#if UNITY_IOS
void itavioManager_OnLinkWithParentApp(bool result)
{
  linkedWithParentApp = result; // True if successfully linked to the ParentApp
}
#endif

(3) To check the link status use the property itavioManager.IsLinked

if(itavioManager.IsLinked) {
    // If Itavio has already been linked against an account
}

Performing a purchase

(1) To approve and start a purchase use:

itavioManager.startDebit<PURCHASE_DELEGATE_TYPE>(AMOUNT, CURRENCY_CODE, PURCHASE_DELEGATE, PURCHASE_DELEGATE_ARGUMENTS);

The PURCHASE_DELEGATE will be called if the account has enough of funds remaining in their balance. (2) Once the purchase has completed from the store inform Itavio that the purchase has been completed

itavioManager.finalizeDebit(true);

Alternatively, if the purchase was cancelled or failed

itavioManager.finalizeDebit(false);

Check for the Parent Itavio App

(1) To determine whether or not the parent app is installed on a user's device use

itavioManager.checkForParent(SHOW_GET_APP_DIALOG);

Passing true will prompt the user to get the app if it is not install. (2) The plugin will respond by firing the OnCheckForParent event

void Start()
{
    itavioManager.OnCheckForParent += itavioManager_OnCheckForParent;
}

void itavioManager_OnCheckForParent(bool result)
{
    hasParentApp = result; // True if ParentApp is installed, otherwise false
}

Check the user's remaining balance

(1) To get the user's remaining balance use

itavioManager.getBalance();

(2) The plugin will respond by firing the OnGetBalance event

void Start()
{
    itavioManager.OnGetBalance += itavioManager_OnGetBalance;
}

void itavioManager_OnGetBalance(double result)
{
  balance = result; // User's remaining balance
}

Additional events

(1) There are some addition events worth noting

void Start()
{
    itavioManager.OnStartDebit += itavioManager_OnStartDebit;
    itavioManager.OnCancelDebit += itavioManager_OnCancelDebit;
    itavioManager.OnCompleteDebit += itavioManager_OnCompleteDebit;
    itavioManager.OnError += itavioManager_OnError;
}

void itavioManager_OnStartDebit(bool result)
{
  if (result)
  {
    // Debit has started ~ this is when the purchase delegate is called
  }
}

void itavioManager_OnCancelDebit(bool result)
{
  if (result)
  {
    // Debit was cancelled
  }
}

void itavioManager_OnCompleteDebit(bool result)
{
  if (result)
  {
    // Debit completed
  }
}

void itavioManager_OnError(int code, string message)
{
  // An error has occurred
}

Additional Build Steps

iOS

iOS Build Step Deprecation

The x86_64 and i386 slices were removed from the shared library in release 0.3.2 so a seperate build script phase is no longer necessary

The itavio.framework includes support for the iOS Simulator. The AppStore will reject an app with those architectures included, the following step will strip out any unused architectures from all the embedded frameworks.

(1) In XCode add a new Run Script build phase. The shell should be /bin/sh and the script should be:

APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"

# This script loops through the frameworks embedded in the application and
# removes unused architectures.
find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
    do
        FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
        FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
        echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"

        EXTRACTED_ARCHS=()

        for ARCH in $ARCHS
        do
            echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
            lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
            EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
        done

        echo "Merging extracted architectures: ${ARCHS}"
        lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
        rm "${EXTRACTED_ARCHS[@]}"

        echo "Replacing original executable with thinned version"
        rm "$FRAMEWORK_EXECUTABLE_PATH"
        mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"
    done

Android

The 'Minimum API Level' must be set to at least Android 4.0.3 'Ice Cream Sandwich' (API level 15).

Testing Tips

Features to test + Detecting/linking with the Parent App + Retrieving the user's balance + Performing a purchase

Best Practices - Unity

Initializing

It is best to initialize Itavio as early as possible, in the Start method of a MonoBehaviour that appears early in the game is recommended. Once it is initialized it will instantiate a a persistent GameObject named ItavioManager.

Check for the Parent App

Check for the parent app and if necessary present the user with the option to get the parent app every time the IAP storefront is opened. In the case that the user has removed the Parent App, they will be presented with the option to disassociate the plugin from their account.

Showing the Get App Dialog

If the user does not have the Parent App, the Get App Dialog should be shown every time the user accesses the IAP storefront until the user completes a transaction.

Linking on iOS

Linking should be performed when the IAP storefront is opened, if the parent app is present. This should only be done once, however there should be a button (Get Itavio/Link Itavio) available on the storefront or the options.

Comments