Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

526 lines (401 sloc) 19.41 kb
Facebook canvas apps (FAQs)
-------------------------------------
- Why am I not getting fb_sig_* parameters anymore?
Under the Migrations tab in your facebook app settings page, your
NEW SDKs setting's set to Enabled. If it's enabled, you will get the
session object via get; otherwise, you will get fb_sig_*
- Why am I not getting the new session object?
See the previous question.
- Why does Kontagent::gen_invite_post_link() include kt_uid in the
invite post link?
fb:request-from's post link needs to be callback url if the app is
an iframe-based app. Facebook passes all its paramters directly to
the callback url in this case instead of the canvas url
(http://apps.facebook/com/[your_app]). When FB forwards back to the
callback url after invite sent, fb_sig_user is no where to be
found. That's why we need to have kt_uid in the invite post's
query_string. This is important because kontagent needs to have
access to the ids parameter for the r parameter in the ins message.
- Why does Kontagent::gen_invite_post_link() include session and
fb_sig_session_key in the invite post link?
Facebook doesn't send any of the fb_sig_* parameter down after an
invite is sent. This presents a problem. Inside kt_landing.php,
since the session information is missing, it will forward the user
back to the login.php url. Consequently, we will miss the recipient
uids. To get around it inside the Kontagent::gen_invite_post_link
function I grab the fb_sig_session_key and the session parameter if
they are present and append them to be part of the post_url, so that
when it arrives at the Kontagent::fbNativeAppRequireLogin() call, no
redirection will happen.
- Why doesn't my stream dialog render properly via calling FB.ui?
Chances are that you are passing in a fair amount of data into the
js call. The js library switches to post if your data is beyond a
certain size. However, when your parameters are being sent to
Facebook, the library doesn't bother to json_encode them.
Read:http://github.com/facebook/connect-js/issues#issue/65
Simply including kt_facebook.js fixes the problem.
- Why can't I use my converted access_token from session_key to make
any of the graph api calls?
Use https://graph.facebook.com/oauth/exchange_sessions instead of
https://graph.facebook.com/oauth/access_token to convert from the
old fb_sig_session_key to the new access_token. The facebook
documentation is a bit inconsistent on this issue. The access_token
you get from calling oauth/access_token will only work for the old
REST API calls while the access_token from calling
oauth/exchange_sessions will work for both the old REST calls and
the GRAPH API.
- Why does Facebook keeps redirecting users outside of Facebook after
login.php with the new permission install page?
To get around this, you can pass in HTTP_REFERER as the current_url
which is passed to the getloginurl() call. In this case HTTP_REFERER
should be your canvas url,
ie. http://apps.facebook.com/your_canvas_app_name. See
KtFacebook::getLoginUrl() in kt_facebook.php for more details.
- My install tracking does work. I did verify that the
post_authorize.php is being called. What's up with that?
Go to your Application settings on Facebook. Click on the Migration
tab, make sure that "New SDKs" and "New Data Permissions" are
enabled.
- A hack that I'm not proud of.
While stream and invites have unique tags generated prior to a user
clicking on the links, ucc messages, such as ad and partner,
generate their unique tags the moment they are clicked on. Similar
to stream and invites, ucc's unique tag needs to be one of the
parameters in the apa message. In order to do that I added a global
variable inside Kontagent::gen_short_tracking_code(). Inside
stripped_kt_args, I check to see if the global variable kt_short_tag
is defined. If so, it will be appended to the query_string. The url
returned by stripped_kt_args will become the final destination url
after authorization.
Functions that are overridden by Kontagent in KtFacebook
---------------------------------------------------------
- getSession()
The way the facebook sdk is set up, your app will not be able to get
a session unless you forward your user to the login.php page first (
See getLoginURL() ). Fortunately, you can convert the old
fb_sig_session_key to get all the new session related information.
- getLoginURL()
You might've already noticed that after a user has authorized your
app, facebook will redirect your user to the url specified by the
next parameter. However, Facebook::getCurrentUrl() returns the
callback url; as a result, your user will be directly outside of
Facebook. To get around this problem, the overridden getLoginURL()
checks to see if the app is a canvas or an iframe app. If so, it
will set the next parameter to HTTP_REFERER, which is
http://apps.facebook.com/[your_canvas_app].
In order to avoid double counting of click messages after an install
and to relate to apa the unique tag information, inside getLoginUrl,
it calls kt->stripped_kt_args() to get rid of all the kt_*
parameters, except for kt_ut and kt_sut. As a result, when it
finally arrives at the landing page, it will still have access to
the tag information. Since the kt_type parameters along with all
other kt_* are missing, it won't send another kontagent click
response message.
Functions that are added by Kontagent in KtFacebook
-----------------------------------------------------
- fbNativeAppRequireLogin()
It behaves the same as require_login() in the old facebook library.
- redirect()
It behaves the same as redirect() in the old facebook library.
- getAccessTokenFromSessionKey()
It calls https://graph.facebook.com/oauth/exchange_sessions with
fb_sig_session_key to get access_token and other related info. See
http://developers.facebook.com/docs/guides/upgrade for more info.
Setup
------
0) Copy the entire kt directory to a location that makes sense to you.
0.1) Edit kt/php/kt_config.php
FB_CALLBACK_URL
---------------
Same as your callback URL specified in your facebook app setup page.
FB_CANVAS_URL
-------------
Same as your canvas URL specified in your facebook app setup page.
FB_ID
-----
Facebook Application ID. Note that this is not the same as your
Facebook API Key.
FB_SECRET
---------
Your App Secret Key.
KT_API_SERVER
-------------
Use api.geo.kontagent.net for production and use
test-server.kontagent.com for development. If KT_API_SERVER is set to
test-server.kontagent.com, you can go to Kontagent.com to check out your
outbound messages to Kontagent in real time under the tools/test
server page. Please note that our test-server.kontagent.com server is not
meant to handle a large volume of traffic. It's meant for you to test
out your instrumentation only.
KT_API_KEY
----------
You'll get it after you've added an app.
SEND_MSG_VIA_JS
---------------
If it's set to true, it will delegate the sending of Kontagnent
messages to your users' browsers. This will free up some bandwidth between
you server and Kontagent.
1) Add the following require_once after your facebook.php include to
your landing page(s) and construct the KtFacebook and the Kontagent
object.
require '[path]/kt_config.php';
require '[path]/kontagent.php';
require '[path]/kt_facebook.php';
require '[path]/kt_landing.php';
$facebook = new KtFacebook(array('appId' => FB_ID,
'secret' => FB_SECRET,
'cookie' => true,
));
$kt = new Kontagent(KT_API_SERVER, KT_API_KEY, 'ffff');
2) Add the following js includes after the facebook JS SDK include
<script src="[path]/kontagent.js"></script>
<script src="[path]/kt_facebook.js"></script>
If you are tracking from the js side only, you will need to define the
following variables: KT_API_SERVER and KT_API_KEY. However, if you
have already included the php files in step one, kt_landing will
generate these parameters for you.
3) require login
To prompt new users the authorization page or to get the session
object for returning users, call $facebook->fbNativeAppRequireLogin();
If you are using Facebook JS SDK to sign in your users, FB.login
will automatically track apa(install event) for you, assuming that
you have done step 2 correctly.
Invite Send (ins)
-----------------
The url generated by gen_invite_post_link() and
gen_invite_content_link() are not calls directly to Kontagent. They
are intermediate links that are intended to be processed by
kt_landing.php, which then will generate a Kontagent REST call.
1) Generate a tracking code.
$long_tracking_code = $kt->gen_long_tracking_code();
2) Append kt_* related parameters to your invite post link's query
string. Note that $long_tracking_code, st1, st2 and st3 have to
match between the gen_invite_post_link and the
gen_invite_content_link calls.
$invite_post_link = $kt->gen_invite_post_link($canvas_callback_url,
$long_tracking_code,
$uid,
[st1 string],
[st2 string],
[st3 string]);
3) Append kt_* related parameters to your invite content links' query string.
$invite_content_link = $kt->gen_invite_content_link($canvas_url,
$long_tracking_code,
[st1 string],
[st2 string],
[st3 string]);
4) Place the generated links at the right place in your FBML.
<fb:request-form
method='POST'
action='<?php echo $invite_post_link?>'
invite='true'
type='join my Smiley group'
content='Would you like to join my Smiley group?
<fb:req-choice url="<?php echo $invite_content_link?>" label="Yes" />'
<fb:multi-friend-selector
actiontext="Invite your friends to join your Smiley group.">
</fb:request-form>
5) Things to look out for.
If you have your fb:request-form nested inside
<fb:serverFbml>
<script type="text/fbml">
<fb:fbml>
</fb:fbml>
</script>
</fb:serverFbml>
, you will find that your action link will not be hit after an invite
is sent out.
If you inspect the rendered HTML, you will find that your action
attribute is an empty string. You can get your action link rendered
properly if you use relative url. For example, instead of
http://..., use index.php?... However, fb:request-form is inside an
iframe. As a result, the actual URL that gets forwarded to is
relative to the URL of the iframe.
Solution: Do not use <fb:serverFbml><script type="text/fbml">. You
can force FB to render FBML by passing in fb_force_mode=fbml as
part of the query string. For example, your invite url might be
http://apps.facebook.com/yourapp/invite.php?fb_force_mode=fbml.
Most likely your app lives inside an iframe, if you have have some
like <a href="<?php echo invite url goes here?>"> is not going to
work. You will need to use javascript to change the parent's frame
url via window.parent.location.href.
Finally, when your action url is hit, your user will be forwarded
outside of facebook. If your app is meant to be living inside of
facebook, this is probably not ideal. To fix this, you can go into
kt_landing.php, add $facebook->redirect([canvas url]) at the end of
the ins case block.
Invite Click (inr)
------------------
Handles by kt_landing.php. If SEND_MSG_VIA_JS is true in
kt_config.php, kontagent.js will handle the sending of the kontagent
message.
Install Tracking (apa)
----------------------
You'll find post_authorize.php in kt/php/. If you already have a
post_authorize page prior to instrumenting with Kontagent, you can
simply include this to the top of your own post_authorize php
file. Otherwise, you'll need to provide Facebook post_authorize.php as
your post authorize URL. Once Facebook forwards back to your landing
page which should already have kt_landing.php include, kt_landing.php
will send Kontagent an apa message.
Install Tracking (apa) Through Javascript
-----------------------------------------
If you include kontagent.js on your landing page, track_install() will
send an install tracking message from the client's browser if it detects
the "installed=1" parameter returned by Facebook. Duplicate install messages
sent from both php and js are avoided through the use of a cookie.
NOTE: Facebook made an API change that stopped sending the necessary data we
need to track uninstalls to the post remove URL. Currently there is no way
to track application removals using our API.
Stream Send via the new Javascript SDK (pst?tu=stream)
------------------------------------------------------
1) Make sure that you have the following js files included in the
order that's shown after the Facebook Javascript include.
<script src="[path]/kontagent.js"></script>
<script src="[path]/kt_facebook.js"></script>
2) If you are supplying st1, st2, and st3, you will need to pass those
in to the FB.ui call. Inside kt_facebook.js, FB.ui is overridden via
prototype. In a nutshell, it will generate a uuid, append all the
necessary kt parameters to all the href attributes. It will also
intercept the callback function and send a pst message if a stream is
actually published
FB.ui(
{
st1 : 'stream_st1',
st2 : 'stream_st2',
st3 : 'stream_st3',
method : 'stream.publish',
...
});
Stream Send via the new Php SDK (pst?tu=stream)
-----------------------------------------------
Just pass in st1, st2, st3 strings if you pass to the api call.
$post_id = $facebook->api(array('method'=>'stream.publish',
'message' => $message,
'attachment' => $attachment,
'action_links' => $action_links,
'st1' => 'st111',
'st2' => 'st222',
'st3' => 'st333'));
Stream Click
------------
Handles by kt_landing.php. If SEND_MSG_VIA_JS is true in
kt_config.php, kontagent.js will handle the sending of the kontagent
message.
Revenue Tracking (php)
----------------------
$kt->track_revenue($uid, [pass in your dollar value in cents]);
For instance, if the value is $2.20, you will need to pass in 220.
Revenue Tracking (js)
---------------------
kt.track_revenue([pass in your dollar value in cents]);
For instance, if the value is $2.20, you will need to pass in 220.
Event_Tracking (php)
--------------------
$kt->track_event($uid, [event name], [value], [level],
[subtype 1 text], [subtype 2 text], [subtype 3 text]);
Event_Tracking (js)
-------------------
kt.track_event([event name], [value], [level],
[subtype 1 text], [subtype 2 text], [subtype 3 text]);
Goal Count (php)
----------------
$kt->track_goal_count($uid, [goal number, 1-4], [increment value]);
$uid: can be a number or an array of uids;
The goal number parameter will simply be 1-4;
Goal Count (js)
---------------
kt.track_goal_count(uid, [goal number, 1-4], [increment value]);
uid: can be a number or an array of uids;
The goal number parameter will simply be 1-4;
Multi Goal Count (php)
----------------------
$kt->track_multiple_goal_counts(uid, array([goal id1] => [goal1 value],
[goal id2] => [goal2 value]));
The goal number parameter will simply be 1-4;
Multi Goal Count (js)
----------------------
kt.track_multiple_goal_counts(uid, {[goal id1]:[goal1 value],
[goal id2]:[goal2 value]);
The goal number parameter will simply be 1-4;
Technical Details:
------------------
Post_authorize.php first convert the fb_sig_session_key into an
access_token if the old sdk is used. With that access_token, it makes
a call to https://api.facebook.com/method/data.setCookie to set a
cookie on facebook to give us a hint later that this user just
authorized your app. The cookie name is kt_just_installed.
Once FB forwards the user back to your landing page. kt_landing.php
first will check to see if the user has already installed your app. If
not, there's no point in determining whether the user has just install
the app. If so, it will first check the browser cookie(not a facebook
cookie) to see if we've already checked for the user's install
status. If the browser cookie is not set, it will then call
data.getcookies to see if kt_just_installed is set. If it's set, an
apa message will be sent to Kontagent. The browser cookie is in place
to prevent future round trip time between Facebook and your app server
caused by calling data.getcookies per page load.
New FB Dialog:
-------------
First in your kt_config.php, set USE_FB_DIALOG_JS to true.
Assumption: You are still using our fbNativeAppRequireLogin() or
getLoginUrl() to redirect your users to the authorization page. You
are not using OAuth Dialog from Facebook.
On the receiving end of an apprequest, our library extracts
Kontagent tracking information from the request object and delete it
automatically. If you'd like to access the request_object, you need to
provide us a callback function, so that we can pass the request_object
back to callback function.
<script>CONTROL_KT_RUN = true;</script>
<script src="../kt/js/kontagent.js?v=44"></script>
<script src="../kt/js/kt_facebook.js?v=44"></script>
<script>
kt.post_invite_click_cb = function(resp){
}
kt.run();
</script>
Otherwise, do
<script src="http://connect.facebook.net/en_US/all.js?v=44"></script>
<script src="../kt/js/kontagent.js"></script>
<script src="../kt/js/kt_facebook.js"></script>
Request Dialog
--------------
Example:
FB.ui(
{
method: 'apprequests',
message: 'You should learn more about this awesome game.',
data: 'tracking information for the user',
st1: 'st111',
st2: 'st22',
st3: 'st333'
},
function(response){
}
);
You simply need to supply the optional subtype1, subtype2, subtype3 parameters.
Upon invite click, Kontagent deletes the request id on your behalf.
Feed Dialog
-----------
Example:
FB.ui(
{
method: 'feed',
name: 'KT Facebook Dialogs',
link: 'http://apps.facebook.com/kontagent_php/',
picture: 'http://fbrell.com/f8.jpg',
caption: 'Caption Goes Here',
description: 'Kontagent integrates with the new facebook dialogs seamlessly!!',
message: 'Kontagent Facebook Dialogs are easy',
st1: 'st111',
st2: 'st22',
st3: 'st3'
},
function(response) {
}
);
Again you simply need to supply the optional subtype1, subytpe2. subtype3 paramters.
We reply on the data field to pass kontagent tracking info between the
sending and the recipient side. We append |kt_data:| to the existing
data field when an invite is about to be sent out. On the receiving
end, we parse out |kt_data:| and extract the string after that.
Jump to Line
Something went wrong with that request. Please try again.