This is the iOS SDK of Pitchtarget. This SDK is forked from adjust.io™ and it is designed as a drop-in replacement for such SDK.
You can read more about adjust.io™ at adjust.io.
These are the minimal steps required to integrate the adjust SDK into your iOS project. We are going to assume that you use Xcode for your iOS development.
If you're using CocoaPods, you can add the following line to your
Podfile
and continue with step 3:
pod 'Pitchtarget', :git => 'https://github.com/pitchtarget/adjust-ios-sdk', :branch => 'master'
Clone this repository or generate a zipball. In the latter case, extract the archive to a folder.
In Xcode's Project Navigator locate the Supporting Files
group (or any other
group of your choice). From Finder drag the Adjust
subdirectory into
Xcode's Supporting Files
group.
In the dialog Choose options for adding these files
make sure to check the
checkbox to Copy items into destination group's folder
and select the upper
radio button to Create groups for any added folders
.
In the Project Navigator select your project. In the left hand side of the main
view select your target. In the tab Build Phases
expand the group Link Binary with Libraries
. On the bottom of that group click on the +
button.
Select the AdSupport.framework
and click the Add
button. In the list of
frameworks select the newly added AdSupport.framework
and change the
attribute Required
to Optional
.
In the Project Navigator open the source file your Application Delegate. Add
the import
statement at the top of the file. In the didFinishLaunching
or
didFinishLaunchingWithOptions
method of your App Delegate add the following
calls to Adjust
:
#import "Adjust.h"
// ...
[Adjust appDidLaunch:@"{YourAppToken}"];
[Adjust setLogLevel:AILogLevelInfo];
[Adjust setEnvironment:AIEnvironmentSandbox];
Replace {YourAppToken}
with your App Token that has been given to you.
You can increase or decrease the amount of logs you see by calling
setLogLevel:
with one of the following parameters:
[Adjust setLogLevel:AILogLevelVerbose]; // enable all logging
[Adjust setLogLevel:AILogLevelDebug]; // enable more logging
[Adjust setLogLevel:AILogLevelInfo]; // the default
[Adjust setLogLevel:AILogLevelWarn]; // disable info logging
[Adjust setLogLevel:AILogLevelError]; // disable warnings as well
[Adjust setLogLevel:AILogLevelAssert]; // disable errors as well
Depending on whether or not you build your app for testing or for production
you must call setEnvironment:
with one of these parameters:
[Adjust setEnvironment:AIEnvironmentSandbox];
[Adjust setEnvironment:AIEnvironmentProduction];
Important: This value should be set to AIEnvironmentSandbox
if and only
if you or someone else is testing your app. Make sure to set the environment to
AIEnvironmentProduction
just before you publish the app. Set it back to
AIEnvironmentSandbox
when you start testing it again.
We use this environment to distinguish between real traffic and artificial traffic from test devices. It is very important that you keep this value meaningful at all times! Especially if you are tracking revenue.
Build and run your app. If the build succeeds, you successfully integrated
Pitchtarget into your app. After the app launched, you should see the debug log
Tracked session start
.
-
If your build failed with the error
Adjust requires ARC
, it looks like your project is not using ARC. In that case we recommend transitioning your project to use ARC. If you don't want to use ARC, you have to enable ARC for all source files of adjust in the target's Build Phases:Expand the
Compile Sources
group, select all adjust files (AjustIo, AI..., ...+AIAdditions, AF..., ...+AFNetworking) and change theCompiler Flags
to-fobjc-arc
(Select all and press theReturn
key to change all at once).
Once you integrated the Pitchtarget SDK into your project, you can take advantage of the following features.
You can tell Pitchtarget about every event you want. Suppose you want to track
every tap on a button. Just call you event button_tap
. In your button's
buttonDown
method you could then add the following line to track the click:
[Adjust trackEvent:@"button_tap"];
You can also append and other custom paramters to any event you track. Just put
some key-value pairs in a dictionary and pass them to the trackEvent
method.
For example, if you want to send more data about your button tap event, add the following lines:
NSMutableDictionary *parameters = [NSMutableDictionary dictionary];
[parameters setObject:@"value" forKey:@"key"];
[parameters setObject:@"bar" forKey:@"foo"];
[Adjust trackEvent:@"abc123" withParameters:parameters];
In that case we would track the event and send a request to:
http://www.adeven.com/callback?key=value&foo=bar
It should be mentioned that we support a variety of placeholders like {idfa}
that can be used as parameter values. In the resulting callback this
placeholder would be replaced with the ID for Advertisers of the current
device. Also note that we don't store any of your custom parameters, but only
append them to your callbacks. If you haven't registered a callback for an
event, these parameters won't even be read.
If your users can generate revenue by clicking on advertisements or making in-app purchases you can track those revenues. If, for example, a click is worth one cent, you could make the following call to track that revenue:
[Adjust trackRevenue:1.0];
The parameter is supposed to be in cents and will get rounded to one decimal point. If you want to differentiate between different kinds of revenue you can simply use different event names for each kind. In that case you would make a call like this:
[Adjust trackRevenue:1.0 forEvent:@"button_tap"];
Again, you can send custom parameters as you would do with normal events.
NSMutableDictionary *parameters = [NSMutableDictionary dictionary];
[parameters setObject:@"value" forKey:@"key"];
[parameters setObject:@"bar" forKey:@"foo"];
[Adjust trackRevenue:1.0 forEvent:@"button_tap" withParameters:parameters];
If you want to track In-App Purchases, please make sure to call trackRevenue
after finishTransaction
in paymentQueue:updatedTransaction
only if the
state changed to SKPaymentTransactionStatePurchased
:
- (void)paymentQueue:(SKPaymentQueue *)queue updatedTransactions:(NSArray *)transactions {
for (SKPaymentTransaction *transaction in transactions) {
switch (transaction.transactionState) {
case SKPaymentTransactionStatePurchased:
[self finishTransaction:transaction];
[Adjust trackRevenue:...];
break;
// more cases
}
}
}
Every time your app tries to track a session, an event or some revenue, you can be notified about the success of that operation and receive additional information about the current install. Follow these steps to implement the optional delegate protocol in your app delegate.
-
Open
AppDelegate.h
and add theAdjust.h
import and theAdjustDelegate
declaration.#import "Adjust.h" @interface AppDelegate : UIResponder <UIApplicationDelegate, AdjustDelegate>
-
Open
AppDelegate.m
and set the adjust delegate indidFinishLaunching
where you already set the adjust environment.[Adjust setEnvironment:AIEnvironmentSandbox]; [Adjust setDelegate:self];
-
Still in
AppDelegate.m
add the following delegate callback function to your app delegate implementation.- (void)adjustFinishedTrackingWithResponse:(AIResponseData *)responseData { }
-
Implement the delegate function.
The delegate function will get called every time any activity was tracked or
failed to track. Within the delegate function you have access to the
responseData
parameter. Here is a quick summary of its attributes:
-
AIActivityKind activityKind
indicates what kind of activity was tracked. It has one of these values:AIActivityKindSession AIActivityKindEvent AIActivityKindRevenue
-
NSString activityKindString
human readable version of the activity kind. Possible values:session event revenue
-
BOOL success
indicates whether or not the tracking attempt was successful. -
BOOL willRetry
is true when the request failed, but will be retried. -
NSString error
an error message when the activity failed to track or the response could not be parsed. Isnil
otherwise. -
NSString trackerToken
the tracker token of the current install. Isnil
if request failed or response could not be parsed. -
NSString trackerName
the tracker name of the current install. Isnil
if request failed or response could not be parsed.
If your app makes heavy use of event tracking, you might want to delay some
HTTP requests in order to send them in one batch every minute. You can enable
event buffering by adding the following line after your setEnvironment:
call
in the didFinishLaunching
method of your Application Delegate:
[Adjust setEventBufferingEnabled:YES];
The adjust-sdk is licensed under the MIT License.
Copyright (c) 2012-2013 adeven GmbH, http://www.adeven.com
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.