Facebook Desktop Canvas App Integration

Overview

To optimize a campaign’s performance and consequently maximize ROI, we need to track various user milestones in the Facebook app. To fully utilize our Bidalgo AI technology and optimize your business goals, we need to track as far down the sales funnel as possible.

The Facebook app integration with Bidalgo is performed through API GET requests.

Bidalgo support three main types of events:

1. Install Events: Used to identify a new Facebook app installation.

2. Monetization Events: Used to track transactions from within the Facebook app. Needs to be triggered when a transaction takes place.

3. Custom Events (Optional): Used for any event that you wish to track and receive a report on.

 

The following steps should be performed:

Step 1 - Define Click URL

Step 2 - Implement Events (Performed by Client Developer)

Step 3 - Testing

Step 4 - Re-attribution Event

 

Note!

We recommend sending us the events from the Server Side (Server to Server), rather than from the client side - as it is more reliable and prevents data discrepancies.  

 

Step 1: Define Click URL - Example

The click URL is the link for the canvas ad. it is made of two parts: 

  1. The URL of the the application
  2. URL parameters

The following is an example of how the above looks in Bidalgo:

When creating an ad in Bidalgo , one of the parameters will be always be added as part of the URL parameters . The name of the param is "uid" and it will need to be passed in every Install API request.

 

Example URL:

http://apps.facebook.com/<YOUR_APP>/?ref=bidalgo&uid=social_121345+_2

We will include two parameters that will help us determine the following:

  • ref = bidalgo - This will help you determine that the campaign was created by Bidalgo. That parameter is optional and can be modified according to advertiser's request.

  • uid=[UID] - The uid value will be dynamically populated by Bidalgo. This provides us with an internal Ad ID. As a result we can determine the exact ad that the user clicked on.

The above parameters will be populated in the URL parameters section in Ad level. 

Please note that additional parameters can be added to the URL.

Please see below an example of how the URL parameters are defined:

image2017-12-26_0-31-52.png

Example URL:

https://apps.facebook.com/waterslots/?ref=bidalgo&uid=social_1234_1

 

Advanced Settings

Please see below the dynamic parameters that can be added to the URL parameters:

image2017-3-22_16-22-21.png

 

Note!

All the ID parameters refer to Bidalgo ID rather than Facebook ID. For example Ad ID is Bidalgo internal ad set id.

http://www.bidalgo.com/?ad_id={%AD_GROUP_ID}

Note!

Website URL - If you are using Website URL, please the edit box above Canvas URL.

 

Step 2: Implement Events (Performed by Client Developer)

 

Install Event 

In order to track app installations, you will need to send us the following request for each new installation.

Request URL

GET  http://events.bidalgo.com/maca-webapp/app/biz/lead

 

Parameters

 
Parameter Name Mandatory Parameter Type Parameter Value Acceptable Values/Examples /comments
channel Yes String A unique identifier for your application. waterworld_wcasino_canvas This should be in the following format: <customer name>_<Appname>_canvas
appUniqueIdentifier Yes String A unique identifier in your application domain for each user. Please do not use any public User Ids per our terms and conditions. for example do not use FB user Id. 197494372329  
uid Yes String Bidalgo Campaign ID. Retrieve from step 1 This field will be sent to your application when the user clicks on the ad. Client Development will need to extract this data and pass it back to us.
country No String ISO "ALPHA-2 Code”, or in other words, must be two capital characters. US DE http://www.nationsonline.org/oneworld/country_code_list.htm
 
 
 
 Install Event Example

http://events.bidalgo.com/maca-webapp/app/biz/lead?channel=waterworld_wcasino_canvas&appUniqueIdentifier=1234567&uid=social_345678_1 

 

Monetization Events 

In order to track user payments, you will need to send us the following request each time the user deposits funds.

Request URL

 

GET http://events.bidalgo.com/maca-webapp/app/biz/event

Parameters

Parameter Name

Mandatory

Parameter Type

Parameter Value

Acceptable Values/Examples

/comments

channel Yes

STRING

A unique identifier for your application. waterworld_wcasino_canvas

This should be in the following format: <customer name>_<Appname>_canvas

This should be identical to the channel provided in the Install event.

appUniqueIdentifier Yes STRING

A unique identifier in your application domain for each user. Please do not use any public User Ids per our terms and

conditions. for example do not use FB user Id

197494372329

 

eventvalue Yes STRING A dynamic parameter sent by your application which translates to the transaction value. 10  
eventName Yes STRING A hard coded value. purchase  
orderID No STRING A unique transaction ID. 1234543 When this is included, Bidalgo will ignore events with the same order ID.

 

Monetization Event Example

http://events.bidalgo.com/maca-webapp/app/biz/event?channel=waterworld_wcasino_canvas&appUniqueIdentifier=197494372329&eventName=purchase&eventValue=10&orderID=1234543

 

Custom Events 

In order to track custom events within the app you will need to send us the following request every time a custom event occurs.

Request URL

 

GET http://events.bidalgo.com/maca-webapp/app/biz/event

Parameters

Parameter Name

Mandatory

Parameter Type

Parameter Value

Acceptable Values/Examples

/comments

channel Yes

STRING

A unique identifier for your application. waterworld_wcasino_canvas

This should be in the following format: <customer name>_<Appname>_canvas

This should be identical to the channel provided in the Install event.

appUniqueIdentifier Yes STRING

A unique identifier in your application domain for each user. Please do not use any public User Ids per our terms and

conditions. for example do not use FB user Id

197494372329

 

eventvalue No STRING A dynamic parameter being sent by your application, which translates to the transaction value. 0  
eventName Yes STRING   FDR FDR - First Day retention
isUnique No STRING If exists and hold the value “1” Bidalgo will remove duplicated events for this event 1  

Custom Event Example

First Day Retention (FDR):

http://events.bidalgo.com/maca-webapp/app/biz/event?channel=waterworld_wcasino_canvas&appUniqueIdentifier=197494372329&eventName=FDR&eventValue=0&isUnique=1

 

For additional information please contact Bidalgo account manager. 

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.