EightDigits-iOS-SDK-x.y.zip dosyası açılır. İçerisinden çıkan EightDigits dizini SDK'nın kendisidir. 8digits entegrasyonu yapmak istediğiniz projeyi Xcode'da açıp, EightDigits ve Utility klasörlerini projenize sürükleyip bırakmanız gereklidir. Bu esnada karşınıza çıkacak olan diyalog kutusunda "Copy items into destination groupʼs folder (if needed)" seçeneğinin seçili olduğundan emin olunuz.

Kopyalama işlemi yapıldıktan sonra projeniz aşağıdaki gibi görünecektir.

EightDigits iOS SDK server ile iletişim için ASI Http kütüphanesini kullanmaktadır. Ayrıca serverside APIden dönen JSON içeriği parse edebilmek için de SBJSON kütüphanesini kullanmaktadır. Bu kütüphanelerin çalışabilmesi için bazı library'lerin link edilmesi gereklidir.

Bu işlemi yapabilmek için sol taraftaki proje ağacında projenizin ismine tıklayıp, Targets'da projenize tıklayıp, Build Phases sekmesi altında Link Binary With Libraries içerisine aşağıdaki kütüphaneleri ekliyoruz.

Ardından projenizi hemen build etmeye çalıştığınızda aşağıdaki ekrandaki gibi bir hata ile karşılaşabilirsiniz.

Bu hata mesajını aşmak için Build Settings altında Search Paths içerisinde User Header Search Paths içerisine aşağıdaki iki satırı eklemek gereklidir.

Yukarıdaki işlemleri yaptıktan sonra build işlemini yaptığınızda projeniz sorunsuz bir şekilde derlenecektir. Kurulum tamamlanmıştır.

Aşağıdaki örneklere devam edebilmek için AppDelegate.h dosyasında yeni bir EightDigitsClient tanımlanması gerekecektir. Örnek bir .h dosyası aşağıdaki gibidir.

					#import 
        #import "EightdigitsClient.h"
        
        @interface AppDelegate : UIResponder  {
            UINavigationController *navigationController;
            EightdigitsClient *eightdigitsClient;
        }
        
        @property (strong, nonatomic) UIWindow *window;
        @property (nonatomic, retain) EightdigitsClient *eightdigitsClient;
        @property (nonatomic, retain) UINavigationController *navigationController;
        
        @end
					
				

Uygulama açılırken tercihen AppDelegate içerisinde yeni bir 8digits session yaratmak gereklidir. Bu işlem aşağıdaki gibi yapılır.

					self.eightdigitsClient = [[EightdigitsClient alloc]
initWithUrlPrefix:@"http://tr-api.8digits.com" trackingCode:@"code"];
[self.eightdigitsClient authWithUsername:@"username" password:@"password"];
				

Tracking Code, username ve password değerleri size daha önce tarafımızca verilmiş olmalıdır. Eğer bilmiyorsanız lütfen konuyla ilgili bir ticket açınız.

8digits uzun süre cevap alamadığı sessionları otomatikman expire etme yeteneğine sahiptir. Bu nedenle session sonlandırmak zorunluluk olmamakla birlikte mümkün olan durumlarda yapılması salık verilir.

					[self.eightdigitsClient endVisit];
				

Bir ekran ile işinizin bittiğini düşündüğünüz anda screen'i ziyaret ettiğinizi belirttiğiniz anda size verilmiş olan hitCode'u kullanarak ekran ile ilişkinizi kopartabilirsiniz. Bu işlemi yapmak için bir UIViewController içerisinde viewWillDissapear: (BOOL) animated metodu ideal lokasyondur.

					- (void)viewWillDisappear:(BOOL)animated {
            [self.eightdigitsClient endScreenWithHitCode:self.hitCode];
        }
				

Bir ekran ile işinizin bittiğini düşündüğünüz anda screen'i ziyaret ettiğinizi belirttiğiniz anda size verilmiş olan hitCode'u kullanarak ekran ile ilişkinizi kopartabilirsiniz. Bu işlemi yapmak için bir UIViewController içerisinde viewWillDissapear: (BOOL) animated metodu ideal lokasyondur. Örneğin bir event aşağıdaki gibi gönderilebilir.

					- (void)viewWillDisappear:(BOOL)animated {
            [self.eightdigitsClient endScreenWithHitCode:self.hitCode];
        }
				

İstenilen herhangi bir anda programatik olarak 8digits'e bir event göndermek mümkündür. Bu event'ler istenilen sayıda ve çeşitlilikte olabilir. Örneğin bir gesture sonrasında, bir upload işlemi sonrasında veya bir butona basılması durumunda bir event gönderimi yapılabilir.

Örneğin bir event aşağıdaki gibi gönderilebilir.

					[self.eightdigitsClient eventWithKey:@"UploadBusinessCard" value:@"1" hitCode:self.hitCode];
				

8digits'te her kullanıcının bir engagement score'u mevcuttur. Bu score o kullanıcının o hizmet veya servise ne kadar ilgili olduğunu gösteren akıllı bir metriktir. Bu değeri okumak için aşağıdaki metod kullanılabilir.

					NSInteger score = [self.eightdigitsClient score];
				

8digits analytics platformunun yanısıra aynı zamanda pek çok oyun mekaniğini de beraberinde sunmaktadır. Bunlardan bir tanesi olan badge altyapısı, serverside'dan tanımlanabilen kurallar sonrasında ziyaretçilerin kazandıkları sanal objelerdir.

Bir kişinin o esnada sahip olduğu badge listesini alabilmek için aşağıdaki gibi bir metod kullanılabilir.

					NSArray *badges = [self.eightdigitsClient badges];
				

Bir kullanıcının badge listesi alındığında o listedeki badge'lerin id'leri geriye dönecektir. ID'si bilinen bir badge'in ise resmini göstermek için aşağıdaki gibi bir kullanım mümkündür.

					UIImage *image = [self.eightdigitsClient badgeImageForId:@"badgeId"];
				

You should create new instance of client in your main activity.

					this.eightDigitsClient = EightDigitsClient.createInstance(this, "", "");
					
				

8Digits client is a singleton class, if you want to get instance of class in other activities, you should type code below in your activity's onCreate event.

					this.eightDigitsClient = EightDigitsClient.getInstance();
				

After getting instance of client, you should create auth token to make requests. To create auth token

					this.eightDigitsClient.authWithUsername("", "");
					
				

Creating auth token in your main activity is enough. You don't have to call this method in other activities.

After creating your session (Creating auth token), you should call newVisit method which creates sessionCode and hitCode. You will use hitCode when you create event for activity. To track what is happening in your activity, client associates event with hitCode.

					int hitCode = this.eightDigitsClient.newVisit("< Title of Visit>", "");
					
				

If you want to create new hitCode you can call newScreen method of client.

					int hitCode = this.eightDigitsClient.newScreen("< Screen Name>", "< Screen Path>");
				

To create a new event, you can use newEvent method. You should pass hitCode for creating a new event. Client sends new events to API asynchronously. So there is no return value.

					this.eightDigitsClient.newEvent("", "", this.hitCode);
					
				

8Digits client is not handling results of asynchronous api calls. If you want to get results of this calls, you can set a listener for them. To do this,

					this.eightDigitsClient.setAsyncResultListener(new AsyncResultListener());
				

You can see a example of listener in com.eightdigits.hello package. AsyncResultListener class is a listener.

You can see example usages of this methods in this application. To import SDK to your application, you can use 8digits-sdk.jar file.

The tracking API will return plain text in Javascript Object Notation (JSON) format in response to any API call. The result object will always have a node called "result" which has a subnode called "code" which will be 0 in case of a successful operation, and any other value in case of an error. If there stands an error code in the code node, there will also be another subnode called "message" which will display a human readable error message which can be used for logging purposes.

authToken:It is the access token which is returned from the authentication process. This token should be stored in a temporary place at the client memory during the session.

trackingCode: Each application being tracked has its own unique tracking code. It is not a confidential information since it can't be used for any purpose without knowing the username & password combination. Tracking code will be provided by 8digits, and should be stored as a constant in your application.

visitorCode:Each visitor must have his/her own unique identifier. The tracking API doesn't provide a mechanism to create an identifier key. Each client has its own platform specific dependencies so the client has to provide its own. For the mobile platforms which are supported with a SDK, please check the SDK source codes.

sessionCode: Each visit from a visitor will be grouped using a session identifier called session code. The system will create reports and tracks a session behviour using this crucial information. The API lets you provide your own session code and if nor provided it will automatically assign one.

hitCode: Each major change in the UI during a session, is called a "new screen" and is symbolized by a "new hit". It is developers' responsibility to call if a change in the UI is a new screen or not. A minor change such as a button push, an alert window or a confirmation display shoudn't be treated as a new hit. Indeed, they are "events". A hit has its own hit code and each event occurred at a screen will provide this code to bind itself to a screen.

Each account has to provide a username and a password pair to identify itself to the system. If authenticated the system will return an auth token. The following requests will also send this token to identify itself.

The system has a powerful mechanism to protect itself from incoming threats. It will block the IP address from authentication after 5 unsuccessfull login attemps. There is also another mechanism that will block a username for 10 minutes after 3 unsuccessfull login attemps in 60 seconds.

Details

URL: http://tr-api.8digits.com/api/auth
Params: username , password
Sample Input:http://tr-api.8digits.com/api/auth?username=[username]&password=[password]
Sample Output:

{"result":{"code":0},"data":{"authToken":"[auth_token]"}}

Your application should get and store the auth token in memory each time the application is launched. The auth token is also bind to an IP address. So it can't be shared nor re-used.

Each time the application is launched a new session must be created. Similar to the web sessions, 8digits behaviour monitoring system also has a session code to group the individual steps as one.

To create a new session client has to provide a "tracking code" which is a hash string that is provided by us. Besides the tracking code the client also has to provide a visitor code. Visitor code is a unique identifier which will allow the 8digits system to track each individual visitor. Mobile platforms such as iOS and Android platforms can use their own platform specific APIs to create a unique device identifier or just use our SDKs which are supported and maintained by us.

For a mobile app, the splash screen is a nice place to create a new session. If a launching page is provided new visit API will also return a hit code for this page besides the session code.

The sessionCode and hitCode parameters are optional. If provided the system will use those values, but create its own if not.

Details

URL http://tr-api.8digits.com/api/visit/create
Params: authToken, trackingCode, visitorCode, pageTitle, path, hitCode(optional), sessionCode(optional), userAgent(optional)
Sample Input: http://tr-api.8digits.com/api/visit/create?authToken=[auth_token]&trackingCode=[tracking_code]&visitorCode=1234567890&pageTitle=LandingScreen&path=/root
Sample Output:

{
    "result":{"code":0},
    "data": {
        "sessionCode":"74164c40-0e1c-4d0b-98fa-5a02c7a03707",
        "hitCode":"35103347"
    }
}
                                

For realistic "time on page" and "time on site" metrics, this API should be called just before the application closed. The 8digits system will work as expected without this API being called, but those two metrics which are quite useful to track visitors' loyalty will give significantly wrong results. It is because the system will wait for a timeout period to label a session as closed and it has no other way to know that the client is actually active or not.

If a visit(session) is closed, either with this method or automatically and a new hit with the same session code is received, a "reborn" routine will take place and the session will be re-awaken if it was never ended.

Details

URL http://tr-api.8digits.com/api/visit/end
Params: authToken, trackingCode, visitorCode, sessionCode
Sample Input: http://tr-api.8digits.com/api/visit/end?authToken=[auth_token]&trackingCode=tracking_code&visitorCode=1234567890&sessionCode=[session_code]
Sample Output:

{"result":{"code":0}}
			

8digits monitoring platform utilizes the reverse IP address lookup mechanism to track visitor location. This facility is run automatically and most of the time accurate in a range of a few kilometers. Unfortunately, this assumption is not always true for mobile devices since mobile broadband providers use different approachs for assigning IP addresses to their subscribers. In such circumstances, if accuracy is important, mobile device can use its own GPS enabled location detection system and use this API to update its location.

Latitude and longitude variables are in decimal format.

Details

URL http://tr-api.8digits.com/api/visit/setLocation
Params: authToken, trackingCode, visitorCode, sessionCode, latitude, longitude, areaCode (opsiyonel), city (opsiyonel), countryCode (opsiyonel), countryName (opsiyonel), hostname (opsiyonel), metropolitanCode (opsiyonel), postalCode (opsiyonel), regionCode (opsiyonel)
Sample Input: http://tr-api.8digits.com/api/visit/setLocation?authToken=[auth_token]&trackingCode=[tracking_code]&visitorCode=123423567890&sessionCode=[session_code]&latitude=11.23412&longitude=12.319318
Sample Output:

{"result":{"code":0}}

Each major change in the UI during a session, is called a "new screen" and is symbolized by a "new hit". You can track how many people have displayed each screen, on which screen they left the application and how long did they stay on any of those screens.

If a screen is not ended it will remain as displayed. If a screen is about to be closed, it is developer's responsibility to call the hit/end API.

Each screen is symbolized by a hit code and this hit code will be used to end the page and send custom events that have occurred on this screen. If client wishes to use its own hitCode generation mechanism, it is also a supported feature. HitCode's must be unique during a session and can repeat itself amongst other sessions.

Details

URL: http://tr-api.8digits.com/api/hit/create
Params: authToken, trackingCode, visitorCode, sessionCode, path, pageTitle, hitCode (opsiyonel)
Sample Input:http://tr-api.8digits.com/api/hit/create?authToken=[auth_token]&trackingCode=[tracking_code]&visitorCode=1234567890&sessionCode=[session_code]&path=/page2&pageTitle=Virtual%20Page%202
Sample Output:

{"result":{"code":0},"data":{"hitCode":"3281359"}}

When finished with a screen, this API needs to be called in order to achieve accurate "time on page" metrics. Otherwise, the page will remain active until the timeout procedure is executed automatically. To end displaying a screen hitCode has to provided with this API call.

Details

URL http://tr-api.8digits.com/api/hit/end
Params: authToken, trackingCode, visitorCode, sessionCode, hitCode
Sample Input:http://tr-api.8digits.com/api/hit/end?authToken=[auth_token]&trackingCode=[tracking_code]&visitorCode=1234567890&sessionCode=[session_code]&hitCode=[hit_code]
Sample Output:

{"result":{"code":0}}

In an event driven approach, the client can generate an event anytime. An event can be a button push, a gesture a scroll or even a server side event that tells that a batch processing of a report has been finished. These events help creating your own business rule engine if used with 8digits' scnearios.

The events are extremely simple key and value pairs. Keys help classify and group these events, whilst values provide a numeric or non-numeric value for those key if it exists. Key field mustn't me empty but value field is optional. If a numeric value is provided 8digits' average of event values, sum of event values reports help you monitor what's going on in your application like you've never done before.

To illustrate, if you consider tracking a button push event, and that button adds an item to the shopping card, then the corresponding key might be: "AddToShopingCard" and the value can be 120.99, which is the price of the item being added to the shopping card.

If an event happens in a client application, then you can provide a hitCode to bind it to a screen and a session. In a server-side environment sessionCode and hitCode can be meaningless so they can just be omitted.

Details

URL: http://tr-api.8digits.com/api/event/create
Params: authToken, trackingCode, visitorCode, sessionCode(opsiyonel), hitCode (opsiyonel), key, value (optional)
Sample Input: http://tr-api.8digits.com/api/event/create?authToken=[auth_token]&trackingCode=[tracking_code]&visitorCode=1234567890&sessionCode=2f26cde3-4edc-4bca-a71e- b13aab234b76&hitCode=44685289&key=ABC&value=11111
Sample Output:

{"result":{"code":0}}

Badges are earned when a visitor finishes a scenario and an "assign badge" action was triggered. Those scenarios and actions are configured at the 8digits administration UI but they run automatically once they are stored. To get the list of the badge ids the visitor is carrying, this API call is used.

Details

URL: http://tr-api.8digits.com/api/visitor/badges
Params: authToken, trackingCode, visitorCode
Sample Input: http://tr-api.8digits.com/api/visitor/badges?authToken=[auth_token]&trackingCode=[tracking_code]&visitorCode=1234567890
Sample Output:

{"result":{"code":0},"data":{"badges":["4f0a9e450364c808e94bfd32"],"count":1}}

The badge id is used to display the badge's icon image using this API. This is a public API and an authentication token is not needed.

Details

URL: http://tr-api.8digits.com/api/badge/image
Params: badgeId
Sample input: http://tr-api.8digits.com/api/badge/image/4fa001140cf2cd0b20173821
Sample output:

Displays the engagement score or the manuel score points depending on the score mechanism profile is using.

Details

URL: http://tr-api.8digits.com/api/visitor/score
Params: authToken, trackingCode, visitorCode
Sample Input: http://tr-api.8digits.com/api/visitor/score?authToken=[auth_token]&trackingCode=[tracking_code]&visitorCode=1234567890
Sample output:

{"result":{"code":0},"data":{"score":30}}