Permalink
Fetching contributors…
Cannot retrieve contributors at this time
691 lines (440 sloc) 19.3 KB

GOW-SDK-IOS

Download

Download the latest sdk version from our server:

Changelog

2.0.20 (Nov 20, 2018)

ADDED

  • The supporting of cross promotion ads was added.

2.0.15 (Sep 25, 2018)

ADDED

  • GetServerTime method was added to get GOW server time.
  • Server time is used in special offers to check the time for the activation.

2.0.14 (Jun 14, 2018)

ADDED

  • redeemable parameter was added to SpecialOffer class.

2.0.13 (May 14, 2018)

ADDED

  • Custom data is supported for special offers.
  • The information about a device's locale is sent to Game of Whales.

2.0.12 (Jan 11, 2018)

ADDED

  • getLeftTime method for special offers.

2.0.11 (Dec 15, 2017)

MODIFIED

  • Push notification about special offer comes at the same time with the special offer (new parameter offer was added):
    void onPushDelivered(SpecialOffer offer, String campID, String title, String message);

  • setPushNotificationsEnable method was added to allow user to turn off the push notifications.

  • Added static methods instead of shared methods.

2.0.10 (Nov 21, 2017)

FIXED

  • pushReacted sending with empty camp.

2.0.9 (Nov 13, 2017)

MODIFIED

  • renamed "Reachability" class to "GWReachability".

2.0.8 (Oct 19, 2017)

FIXED

  • bug with pushDelivered and pushReacted events for push campaigns.

2.0.7 (Oct 18, 2017)

FIXED

  • bug with OnPushDelivered callback for empty push notification campaign.
  • bug with redeemable once special offer: they could be used many times.

Implementation Guide

Common

Step 1

Add GameOfWhales.framework to Linked Frameworks and Libraries XCODE section of your project.

Load GameOfWhalesBundle.bundle file to your project.

Than add it to Build Phase -> Copy Bundle Resources.

Step 2

Add GWGameKey parameter to info.plist and specify your game key.

SWIFT

Step 3

Call initialize method when you launch your app.

import GameOfWhales
...

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool
{
  ...
   Bool debugLog = false;
   GW.initialize( launchOptions, false);

Purchases

Check that iOS Bundle Identifier (for iOS app) has been filled on Game Settings page before you will make a purchase.

Step 4 (only if you use in-app purchases)

Register a purchase with purchaseTransaction method.

 func paymentQueue(_ queue: SKPaymentQueue, updatedTransactions transactions: [SKPaymentTransaction]) {
    for t in transactions
       if t.transactionState == SKPaymentTransactionState.purchased
           GW.purchaseTransaction(t, product: product!);

Special Offers

Before any product can be used in a special offer it has to be bought by someone after SDK has been implemented into the game. Please make sure your game has at least one purchase of the product that is going to be used in the special offer. If you want to create a special offer for in game resource, please, make sure your game has at least one converting event with the appropriate resource.

Step 5

If you want to use special offers, you need to implement some methods of GWDelegate protocol and call add method.

class ViewController: UIViewController, GWDelegate     
...

     override func viewWillAppear(_ animated: Bool) {
         GWManager.add(self)
     }
   
     override func viewDidDisappear(_ animated: Bool) {
     
        //remove self from delegates
        GWManager.remove(self)

Step 6

Add the following methods:

 func onPurchaseVerified(_ transactionID: String, state: String)
 {
 }
 
 func specialOfferDisappeared(_ specialOffer: GWSpecialOffer)
 {
 }
 
 func specialOfferAppeared(_ specialOffer: GWSpecialOffer) 
 {
 }
 
 func onPushDelivered(_ offer:GWSpecialOffer?, camp: String, title:String, message:String)
 {
 }

The verify state can be:

  • GW_VERIFY_STATE_LEGAL - a purchase is normal.
  • GW_VERIFY_STATE_ILLEGAL - a purchase is a cheater's.
  • GW_VERIFY_STATE_UNDEFINED - GOW server couldn't define the state of a purchase. 

Step 7

In order to receive a special offer call the following method:

   let offer = GW.getSpecialOffer(productIdentifier);
   if (offer != nil)
   {   ...

A special offer can influence a product's price:

   if (offer?.hasPriceFactor())!
   {
       price = Int(Float(price) * (offer?.priceFactor)!);
   }

A special offer can also influence count (count of coins, for example) which a player receive by purchase:

   if (offer?.hasCountFactor())!
   {
       coins = Int(Float(coins) * (offer?.countFactor)!);
   }

It's possible to pass custom data to special offers. In order to get the data in game's side, use customValues parameter of SpecialOffer class.

    let str = offer.customValues.valueForKey("your_string") as? NSTring
    let number = offer.customValues.valueForKey("your_number") as? NSNumber
    let boolean = offer.customValues.valueForKey("your_bool") as? NSNumber

Notifications

Step 8 (for iOS only)

Enable the Push Notifications option in the Xcode.

Step 9

In order to send notifications from GOW server it is necessary to pass the token information to the server.

    //FIREBASE
    let token = FIRInstanceID.instanceID().token();
    GW.registerDeviceToken(with: token!, provider:GW_PROVIDER_FCM);
    
    //APN
    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        GW.registerDeviceToken(with: deviceToken, provider: GW_PROVIDER_APN)

Step 10

To get information about a player's reaction on notifications add the following methods to AppDelegate:

func application(_ application: UIApplication,
                     didReceiveRemoteNotification userInfo: [AnyHashable : Any],
                     fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void)
                     {
                     
                     GWManager.receivedRemoteNotification(userInfo, with: application, fetchCompletionHandler: completionHandler);
                     
                     }

Step 11 (Only if notifications are shown inside your app by using the game's code)

In order to send the information to Game of Whales regarding a player's reaction on a notification (to increase push campaign's Reacted field) of an already started app call the following method:

      func onPushDelivered(_ offer:GWSpecialOffer?, camp: String, title:String, message:String) {
            //Show message and call:
            GW.reactedRemoteNotification(withCampaign: camp);

Step 12

In order to enable or disable push notifications, use the following method:

   GW.setPushNotificationsEnable(false);

In order to check notifications implementation send a test notification.

Profiles

Step 13

You can send additional data about your players by using the profile method. profile method should be called if key parameters of your app or a player have changed.

In order to work with AI offers you should send at least 5 number-type properties and at least one progress based parameter.

If you send more than 3000 properties, Game of Whales will sort all properties alphabetically and will save only the first 3000.

If the length of a string-type property is more than 64 characters, Game of Whales will save only the first 64 characters.

For example:

    GW.profile(["coins":1000, "class":"wizard", "gender":true, "locatiom":"A"]);

Converting

Step 14

converting method should be called when you buy or get some in-game objects, coins, currency, etc.

For example:

Someone bought one bike_1 for 1000 coins and 50 gas. You should call the following method for this purchase:

      GW.converting(["coins":-1000, "gas":-50, "bike_1":1], place: "bank")

You can also use the following methods:

consume - to buy items for game currency. For example:

    GW.consumeCurrency("coins", number:1000, sink:"gas", amount:50, place:"shop")

It means that someone spent 1000 "coins" for 50 "gas" in "shop".

acquire - for in-app purchases. It's important to call acquire method after InAppPurchased. For example:

    GW.acquireCurrency("coins", amount:1000, source:sku, number:1, place:"bank")

It means that someone has acquired 1000 "coins" for 1 "sku" in "bank".

Cross promotion ads

It's supported since version 2.0.20 of SDK for iOS.

To handle the ads set in Game of Whales, you need to do some actions:

Step 15

Subscribe to the following events to get the information about the current state of the ads by using GWDelegate (the same as you do it on Step 6):

func onAdLoaded() 
 {
 }
    
 func onAdLoadFailed() 
 {
 }
    
 func onAdClosed() 
 {
 }

Step 16

Start to load the ads at any place of your code (for example, during the launch of the game):

  GW.loadAd()

Step 17

Add the following code to the part of your game where you want to show the ads:

if (GW.isAdLoaded())
    GW.showAd()
else
    GW.loadAd()

Objective-C

Step 3

Call initialize method when you launch your app.

#import <GameOfWhales/GameOfWhales.h>
...
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    ...
    BOOL debugLog = false;
    [GW initialize:launchOptions :debugLog];

Purchases

Check that iOS Bundle Identifier (for iOS app) has been filled on Game Settings page before you will make a purchase.

Step 4 (only if you use in-app purchases)

Register a purchase with purchaseTransaction method.

- (void)paymentQueue:(SKPaymentQueue *)queue updatedTransactions:(NSArray *)transactions {
     for(SKPaymentTransaction * t in transactions)
         if (t.transactionState == SKPaymentTransactionStatePurchased)
                 [GW PurchaseTransaction:t product:product];
}

Special Offers

Before any product can be used in a special offer it has to be bought by someone after SDK has been implemented into the game. Please make sure your game has at least one purchase of the product that is going to be used in the special offer. If you want to create a special offer for in game resource, please, make sure your game has at least one converting event with the appropriate resource.

Step 5

If you want to use special offers, you need to implement some methods of GWDelegate protocol and call addDelegate method.

@interface ViewController : UIViewController<GWDelegate>
...
- (void)viewDidLoad {
    [super viewDidLoad];
    
    [GW AddDelegate:self];
}

- (void)viewDidDisappear:(BOOL)animated
{
    [GW RemoveDelegate:self];
}

Step 6

Add the following methods:

- (void)specialOfferAppeared:(nonnull GWSpecialOffer *)specialOffer
{
    
}

- (void)specialOfferDisappeared:(nonnull GWSpecialOffer *)specialOffer
{
    
}

- (void)onPushDelivered:(nullable GWSpecialOffer*) offer camp:(nonnull NSString *)camp title:(nonnull NSString*)title message:(nonnull NSString*)message
{
    
}

- (void)onPurchaseVerified:(nonnull NSString*)transactionID state:(nonnull NSString*)state
{
    
}

The verify state can be:

  • GW_VERIFY_STATE_LEGAL - a purchase is normal.
  • GW_VERIFY_STATE_ILLEGAL - a purchase is a cheater's.
  • GW_VERIFY_STATE_UNDEFINED - GOW server couldn't define the state of a purchase. 

Step 7

In order to receive a special offer call the following method:

    GWSpecialOffer* so = [GW GetSpecialOffer:productIdentifer];
    if (so != nil)
    {
      ...
    }
    

A special offer can influence a product's price:

   if ([so hasPriceFactor])
   {
       price *= so.priceFactor;
   }

A special offer can also influence count (count of coins, for example) which a player receive by purchase:

   if ([so hasCountFactor])
   {
       coins *= so.countFactor;
   }

It's possible to pass custom data to special offers. In order to get the data in game's side, use customValues parameter of SpecialOffer class.

   NSString * str = [specialOffer.customValues objectForKey:@"your_str"];
   NSNumber * number = [specialOffer.customValues objectForKey:@"your_int"];
   NSNumber * boolean = [specialOffer.customValues objectForKey:@"your_bool"];

Notifications

Step 8 (for iOS only)

Enable the Push Notifications option in the Xcode.

Step 9

In order to send notifications from GOW server it is necessary to pass the token information to the server.

 - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
 
    //FIREBASE
    [GW RegisterDeviceTokenWithString:[[FIRInstanceID instanceID] token] provider:GW_PROVIDER_FCM];
    
    //APN
    [GW RegisterDeviceTokenWithData:deviceToken provider:GW_PROVIDER_APN];
}

Step 10

To get information about a player's reaction on notifications add the following methods to AppDelegate:

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
    fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler
   {
     [GW ReceivedRemoteNotification:userInfo withApplication:application fetchCompletionHandler:completionHandler]; 
   }

Step 11 (Only if notifications are shown inside your app by using the game's code)

In order to send the information to Game of Whales regarding a player's reaction on a notification (to increase push campaign's Reacted field) of an already started app call the following method:

- (void)onPushDelivered:(nullable GWSpecialOffer*) offer camp:(nonnull NSString *)camp title:(nonnull NSString*)title message:(nonnull NSString*)message
{
    //Show the notification to a player and then call the following method
    [GW ReactedRemoteNotificationWithCampaign:camp];
}

Step 12

In order to enable or disable push notifications, use the following method:

  [GW SetPushNotificationsEnable:false];

In order to check notifications implementation send a test notification.

Profiles

Step 13

You can send additional data about your players by using the Profile method. Profile method should be called if key parameters of your app or a player have changed.

In order to work with AI offers you should send at least 5 number-type properties and at least one progress based parameter.

If you send more than 3000 properties, Game of Whales will sort all properties alphabetically and will save only the first 3000.

If the length of a string-type property is more than 64 characters, Game of Whales will save only the first 64 characters.

For example:

    NSMutableDictionary *changes = [NSMutableDictionary dictionary];
    message[@"coins"] = @1000;
    message[@"class"] = @"wizard";
    message[@"gender"] = @TRUE;
    message[@"location"] = @"A";
    [GW Profile:changes];

Converting

Step 14

Converting method should be called when you buy or get some in-game objects, coins, currency, etc.

For example:

Someone bought one bike_1 for 1000 coins and 50 gas. You should call the following method for this purchase:

        NSMutableDictionary *resources = [NSMutableDictionary dictionary];
        resources[@"coins"] = @-1000;
        resources[@"gas"] = @-50;
        resources[@"bike_1"] = 1;
        [GW Converting:resources place:@"bank"]

You can also use the following methods:

Consume - to buy items for game currency. For example:

    [GW ConsumeCurrency:@"coins" number:@1000 sink:@"gas" amount:@50 place:@"shop"];

It means that someone spent 1000 "coins" for 50 "gas" in "shop".

Acquire - for in-app purchases. It's important to call acquire method after InAppPurchased. For example:

    [GW AcquireCurrency:@"coins: amount:@1000 source:sku number:@1 place:@"bank];

It means that someone has acquired 1000 "coins" for 1 "sku" in "bank".

Cross promotion ads

It's supported since version 2.0.20 of SDK for iOS.

To handle the ads set in Game of Whales, you need to do some actions:

Step 15

Subscribe to the following events to get the information about the current state of the ads by using GWDelegate (the same as you do it on Step 6):

- (void)onAdLoaded
{

}

- (void)onAdLoadFailed
{

}

- (void)onAdClosed
{

}

Step 16

Start to load the ads at any place of your code (for example, during the launch of the game):

  [GW LoadAd];

Step 17

Add the following code to the part of your game where you want to show the ads:

if ([GW IsAdLoaded])
        [GW ShowAd];
else
        [GW LoadAd];

You can find an example of using the SDK here.

Run your app. The information about it began to be collected and displayed on the dashboard. In a few days, you will get data for analyzing.

This article includes the documentation for Game of Whales iOS Native SDK. You can find information about other SDKs in documentation about Game of Whales.

FAQ

To fix the error

NSErrorFailingURLStringKey The resource could not be loaded because the App Transport Security policy
requires the use of a secure connection.

make the following settings in info.plist: