Authentication
While you can provide access to a variety of content such as food search and nutritional information to anyone viewing your JavaScript application,
there are some features that are only available to authenticated users. Examples of this are the food diary, exercise diary and weight chart.
These features require that users are authenticated as the core function that these features provide is storage and retrieval of history data on a per-user basis.
There are two ways that user authentication may be achieved:
In addition, you may wish to segment your application so that certain features are available to casual (unauthenticated) users of your site while other features
require that users are authenticated. For more information, see
Deferred profile and session creation.
Letting FatSecret.com manage your user's profiles
Whenever a user takes an action which requires them to be logged in, the JavaScript API will automatically load the
profile.sign_in canvas
into the current
container. The
profile.sign_in
canvas advises the user that they need to sign in to proceed and provides a link to FatSecret.com where the user must authenticate themselves.
If user approves the referring domain on FatSecret.com, and permits access to their account, the user is redirected back to the referring page with additional
credentials so that they are subsequently authenticated and recognized.
What does all this mean? Simply put, you don't have to worry about doing a thing as we will handle the whole authentication process for you.
Managing your own user profiles
By managing your own FatSecret Platform application user profiles you can provide a seamless experience for your users, so they need never leave your site to authenticate
themselves. You can also use the authentication protocols to direct non-registered visitors to your site to sign-up/register in order to access restricted content provided
by the platform application.
To understand how this works, lets summarize how users are authenticated in a Platform application:
When a Platform application is executing for an authenticated user, a HTTP cookie is used to store session and signing credentials for the user. When you manage your own
profiles, you are responsible for setting up this cookie (when you let FatSecret.com manage your user’s profiles this cookie is setup automatically for you).
There are just two simple steps to setting up the credentials for your users:
- Obtain a valid session for your user using the FatSecret Platform REST API; and
- Provide this session information to the JavaScript API.
Obtaining a valid session for your user:
In order to obtain a valid FatSecret Platform session for your users you must use the
FatSecret Platform REST API,
and in particular the
profile.request_script_session_key
method call. The
profile.request_script_session_key method
is
the only method you need use to enable profile integration, and
Client Libraries and associated examples are
available in a number of programming languages to assist you.
The
profile.request_script_session_key method call provides
session information for your users in one of two formats:
- As a value to be used as a query parameter to the URL "http://platform.fatsecret.com/js"
- As a cookie value that you can explicitly set in the HTTP response of your page.
Examples of how each type of value may be consumed are provided below:
Providing the session information to the JavaScript API:
The
profile.request_script_session_key method call includes a
cookie parameter. When the
cookie parameter is
false the session key returned is in a format suitable for appending to the JavaScript API URL. When the
cookie parameter is
true the session key returned is in a format suitable for being programmatically written in the HTTP response as the value of a cookie named
"fatsecret_session_key"
E.G.: appending the session information to the JavaScript API URL (when cookie = false):
<?php
$API = new FatSecretAPI($apiKey, $apiSecret);
$auth = Array(user_id=>$local_user_id);
$sessionKey;
$API->ProfileRequestScriptSessionKey($auth, null, null, null, false, $sessionKey);
?>
<script
src="http://platform.fatsecret.com/js?fatsecret_session_key=<?php print $sessionKey ?>"></script>
E.G.: programmatically setting the session information in the HTTP response (when cookie = true):
<?php
$API = new FatSecretAPI($apiKey, $apiSecret);
$auth = Array(user_id=>$local_user_id);
$sessionKey;
$API->ProfileRequestScriptSessionKey($auth, null, null, null, true, $sessionKey);
setCookie("fatsecret_session_key", $sessionKey);
?>
<script
src="http://platform.fatsecret.com/js"></script>
Note that the session credentials need only be set once for a user using your application. The duration and expiry setting of the session may be adjusted according to parameters
specified with the
profile.request_script_session_key method
call (see the REST documentation for further details).
It is recommended that you test for the existence of a valid "fatsecret_session_key" cookie in the HTTP request to your server rather than generate a new a
session for each request.
Deferred profile and session creation
Many Internet sites and web pages permit unauthenticated (casual) visitors to view their content. You may wish to include a FatSecret Platform application on pages such as this.
You can enable this behavior by
manually loading content and
adjusting the navigation
so that users are only presented with content that does not require authentication.
However, in a more richly integrated application, you can expose additional features to unauthenticated visitors, such as the Food Diary and Activity Diary, and
prompt users to sign-in or register on your site in order to activate these features.
You can achieve this behavior by:
Choose to adjust the profile.sign_in canvas when you want to keep the user within your FatSecret Platform application during the authentication process (you may provide a
link to your own authentication web page within this canvas). Choose to re-direct the profile.sign_in canvas when you want to immediately direct users to your own
authentication web page.
Adjusting the profile.sign_in canvas:
Whenever a user performs an action which requires that they are authenticated in order to proceed, the JavaScript API automatically loads the
profile.sign_in canvas in the current
container. As
described above, the default template for this
canvas contains a link to FatSecret.com that users can follow in order to authenticate. If you
manually load content for this
canvas you can provide whatever additional information and links are
necessary to log in on your own site, rather than providing a log in link to FatSecret.com. E.G.:
<script
src="http://platform.fatsecret.com/js?key=XXXXX&auto_template=false"></script>
...
Login canvas content here
...
Re-directing the profile.sign_in canvas:
You may choose to bypass the standard
profile.sign_in canvas
all together and immediately direct users to your own verification and/or login screen. You can do this by redirecting all
profile.sign_in
canvas calls to your login page using the
fatsecret.setCanvasUrl script function.
<script>
fatsecret.setCanvasUrl("profile.sign_in", "http://www.example.com/login.html");
</script>
In the above example, users will be immediately directed to http://www.example.com/login.html when they are not authenticated and they perform an action that requires authentication.
Note that when you defer profile and session creation it is suggested that you use the profile management instructions described above to establish and set the FatSecret Platform
JavaScript API session credentials for your users at the point that they authenticate on your site.
See the
Sample Code for overriding the
profile.sign_in canvas.