/
Facebook.yml
2075 lines (1734 loc) · 77.5 KB
/
Facebook.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
name: Modules.Facebook
summary: |
Add-on Facebook module.
description: |
The Facebook module is used for connecting your application with
Facebook. This module supports the following features:
* Logging in to Facebook and authorizing your application with either the
[Login button](Modules.Facebook.LoginButton) or programatically.
* Making requests through the Facebook Graph API using the
[requestWithGraphPath()](Modules.Facebook.requestWithGraphPath) method.
* Sharing content using Facebook dialogs or the [Like button](Modules.Facebook.LikeButton).
**Using Facebook module with iOS 10 and Xcode 8**
To log in using facebook, we now have to include an entitlements file that enables Keychain Sharing
Capabilities. To do so, create a `/platform/ios/<appname>.entitlements` file with this content
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>keychain-access-groups</key>
<array>
<!-- Application ID same as the id value in the tiapp.xml file -->
<string>APP_ID</string>
</array>
</dict>
</plist>
**Note:** As of April 30th, 2015, Facebook no longer supports version 1.0 of their API, which
includes the FQL and REST APIs. Only the Graph APIs will be supported.
**Migration from the Facebook module v4.x to v5.x**
* **dialog() method** -- [presentWebShareDialog()](Modules.Facebook.presentWebShareDialog) is
deprecated and removed. The module will auto determine if you have a native Facebook App installed.
[canPresentShareDialog()](Modules.Facebook.canPresentShareDialog) is also deprecated and removed.
For more details, see 'Share Dialogs' and 'Request Dialogs' below.
* **presentShareDialog() method** -- 'name' parameter is deprecated and replaced with 'title'.
'caption' parameter is deprecated and removed.
* **presentSendRequestDialog() method** -- 'to' parameter is deprecated and replaced with 'recipients'.
There are a few new parameters as well, for more details,
see [presentSendRequestDialog()](Modules.Facebook.presentSendRequestDialog)
The following APIs were removed due to changes in the native Facebook SDKs and
removal of the Facebook v1.0 REST APIs:
* **appid property** -- The Facebook application ID can no longer be set programmatically
in the application. Set the Facebook application ID in the `tiapp.xml` file.
For more details, see 'Getting Started' below for more details.
**Migration from the Facebook module v3.x to v4.x**
The following APIs were removed due to changes in the native Facebook SDKs and
removal of the Facebook v1.0 REST APIs:
* **appid property** -- The Facebook application ID can no longer be set programmatically
in the application. Set the Facebook application ID in the `tiapp.xml` file.
For more details, see 'Getting Started' below for more details.
* **dialog() method** -- Use either
[presentSendRequestDialog()](Modules.Facebook.presentSendRequestDialog),
[presentInviteDialog()](Modules.Facebook.presentInviteDialog),
[presentMessengerDialog()](Modules.Facebook.presentMessengerDialog),
[presentShareDialog()](Modules.Facebook.presentShareDialog) or
[presentWebShareDialog()](Modules.Facebook.presentWebShareDialog).
For more details, see 'Share Dialogs' and 'Request Dialogs' below.
* **forceDialogAuth property** -- On Android, you can force dialog authorization with the
[LoginButton.sessionLoginBehavior](Modules.Facebook.LoginButton.sessionLoginBehavior) property.
* **publishInstall() method** -- The underlying Facebook API has been deprecated and
is now handled automatically by the module.
* **request() method** -- Due to the removal of the Facebook v1.0 APIs,
all applications should call the Graph APIs instead. If you make any REST API calls
with the `request()` method, transition to the Graph APIs and use the
[requestWithGraphPath()](Modules.Facebook.requestWithGraphPath) method.
* **reauthorize() method** -- To request additional Facebook permissions once the
user authorizes the application, use either the
[requestNewReadPermissions()](Modules.Facebook.requestNewReadPermissions) or
[requestNewPublishPermissions()](Modules.Facebook.requestNewPublishPermissions).
For more details, see "Manage Read and Write Permissions" below.
* **LoginButton style property** -- Facebook redesigned its Login button and the
style can no longer be changed.
## Getting Started
To use the Facebook module, you need a Facebook application. To create a Facebook App,
go to the Facebook Developer App: [developers.facebook.com/apps](https://developers.facebook.com/apps).
- Edit the `modules` section of your tiapp.xml file to include this module:
<modules>
<!-- Add the appropriate line(s) to your modules section -->
<module platform="android">facebook</module>
<module platform="iphone">facebook</module>
</modules>
- Instantiate the module with the `require('facebook')` method, then make subsequent API calls
with the new Facebook object.
var fb = require('facebook');
fb.permissions = [FACEBOOK_APP_PERMISSIONS];
fb.initialize();
fb.authorize();
### Additional iOS Setup Steps
For the iOS platform, in the `ios plist dict` section of your `tiapp.xml` file, add the following keys:
* `FacebookAppID` key with your Facebook App ID as the string value
* `FacebookDisplayName` key with your Facebook App name (the one from `developer.facebook.com`) as the string value
* `CFBundleURLTypes` key with a single-element array containing a dict as the value, where the dict contains:
* `CFBundleURLName` key with the application app ID (same value as the `id` in the `tiapp.xml` file) as the string value
* `CFBundleURLSchemes` key with a single-element array containing the Facebook App ID prefixed with `fb` as a string value
For example:
<ti:app>
<ios>
<plist>
<dict>
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLName</key>
<!-- Application ID same as the id value in the tiapp.xml file -->
<string>APP_ID</string>
<key>CFBundleURLSchemes</key>
<array>
<!-- Prefix the Facebook App ID with 'fb' -->
<string>fbFACEBOOK_APP_ID</string>
</array>
</dict>
</array>
<key>FacebookAppID</key>
<!-- Facebook App ID -->
<string>FACEBOOK_APP_ID</string>
<key>FacebookDisplayName</key>
<!-- Facebook App Name from developer.facebook.com -->
<string>FACEBOOK_APP_NAME</string>
</dict>
</plist>
</ios>
</ti:app>
To enable the use of Facebook dialogs (e.g., Login, Share), you also need to include the following key and values in `tiapp.xml`
to handle the switching in and out of your app:
<key>LSApplicationQueriesSchemes</key>
<array>
<string>fbapi</string>
<string>fb-messenger-api</string>
<string>fbauth2</string>
<string>fbshareextension</string>
</array>
If you are using the older Ti.Facebook Module 4.0.5 and wish to support iOS9, you will instead need to include the following key
and values in `tiapp.xml` to handle the switching in and out of your app:
<key>LSApplicationQueriesSchemes</key>
<array>
<string>fbapi</string>
<string>fbapi20130214</string>
<string>fbapi20130410</string>
<string>fbapi20130702</string>
<string>fbapi20131010</string>
<string>fbapi20131219</string>
<string>fbapi20140410</string>
<string>fbapi20140116</string>
<string>fbapi20150313</string>
<string>fbapi20150629</string>
<string>fbauth</string>
<string>fbauth2</string>
<string>fb-messenger-api20140430</string>
</array>
For iOS9 and titanium 5.0.0.GA and above, App Transport Security is disabled by default.
If you choose to enable it, you have to set the following keys and values in `tiapp.xml` <ios> section for facebook module:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>facebook.com</key>
<dict>
<key>NSIncludesSubdomains</key>
<true/>
<key>NSExceptionRequiresForwardSecrecy</key>
<false/>
</dict>
<key>fbcdn.net</key>
<dict>
<key>NSIncludesSubdomains</key>
<true/>
<key>NSExceptionRequiresForwardSecrecy</key>
<false/>
</dict>
<key>akamaihd.net</key>
<dict>
<key>NSIncludesSubdomains</key>
<true/>
<key>NSExceptionRequiresForwardSecrecy</key>
<false/>
</dict>
</dict>
</dict>
### Additional Android Setup Steps
Since Facebook module v4.0.0, for the Android platform, you need to:
* Add the Facebook Login activity to the Android manifest
* Add the Facebook App ID to the Android resources `string.xml` file
* Create a Facebook proxy and associate it with the current active activity
**Modify the Android Manifest**
Add the Facebook Login activity to the `android manifest` section of your `tiapp.xml` file.
You may need to add the `manifest` and `application` elements.
<ti:app>
<android xmlns:android="http://schemas.android.com/apk/res/android">
<manifest>
<application>
<activity android:name="com.facebook.FacebookActivity"
android:theme="@android:style/Theme.Translucent.NoTitleBar"
android:label="YourAppName"
android:configChanges="keyboard|keyboardHidden|screenLayout|screenSize|orientation" />
<meta-data android:name="com.facebook.sdk.ApplicationId" android:value="@string/facebook_app_id"/>
</application>
</manifest>
</android>
<ti:app>
**Add the Facebook App ID to Android Resources**
Add a string element to the `/platform/android/res/values/strings.xml` file with the `name`
attribute set to `facebook_app_id` and the node text set to your Facebook App ID. Create the
file if it does not exist.
<resources>
<string name="facebook_app_id">FACEBOOK_APP_ID</string>
</resources>
**Create a Facebook Proxy**
Use the [createActivityWorker()](Modules.Facebook.createActivityWorker) method to create a
Facebook proxy. Pass the method a dictionary with the `lifecycleContainer` property set to
the current active instance of a standalone Window (window not contained in a tab group) or TabGroup.
Create the proxy before calling the `open()` method on either the window or tab group.
The Facebook module needs to hook into the lifecycle events of the current active activity
in order to synchronize its state between various activities in the application, for example,
to update the label of the Login button when the user logs in or out of Facebook.
Attach the proxy to the Window or TabGroup object, so it does not get garbage collected.
win.fbProxy = fb.createActivityWorker({lifecycleContainer: win});
## Module API Usage
### Facebook Login and Authorization
To use Facebook, a user must logged into Facebook and explicitly authorize the application to
perform certain actions, such as accessing profile information or posting status messages.
There are two ways to initiate the login process:
* Call [authorize](Modules.Facebook.authorize) to prompt the user to login and authorize
the application. Before calling this method, set the <Modules.Facebook.permissions> property
if additional permissions are needed.
* Create a Facebook [LoginButton](Modules.Facebook.LoginButton) to allow the user to
log in if desired. You can add either read permissions or write permissions,
otherwise the default is to request for the `public_profile` permission.
Note that Facebook does not support setting both `readPermissions` and `publishPermissions`
properties at the same time when using the LoginButton.
Which approach you take depends on your UI and how central Facebook is to your
application.
### Manage Read and Write Permissions
In order to read or write content to a user's Facebook page, you need to request permission from
the user. You can either request permissions when the user authorizes your application or
request permissions on the fly.
Before the user logs in and authorizes the application, you can request permissions for the
application to use by either:
* Setting the <Modules.Facebook.permissions> property if you are using `authorize()` method to
have the user login and authorize the application.
* Setting either the [readPermissions](Modules.Facebook.LoginButton.readPermissions) or
[publishPermissions](Modules.Facebook.LoginButton.publishPermissions) on an instance of a LoginButton.
Do not set both properties or the application will throw an error.
For a complete list of permissions, see the [official Facebook Permissions Reference](https://developers.facebook.com/docs/facebook-login/permissions/)
**Refresh Application Permissions**
Since the user can selectively turn application permissions on and off from their Facebook
page, the application may need to refresh its granted permissions.
To refresh the application's permissions, call the
[refreshPermissionsFromServer()](Modules.Facebook.refreshPermissionsFromServer) method, then
listen for the <Modules.Facebook.tokenUpdated> event to be notified when permissions are updated.
fb.addEventListener('tokenUpdated', function(e) {
Ti.API.info('Updated permissions: ' + JSON.stringify(fb.permissions));
});
fb.refreshPermissionsFromServer();
**Request Additional Read Permissions**
To request additional read permissions once the user authorizes your application, use the
[requestNewReadPermissions()](Modules.Facebook.requestNewReadPermissions) method.
Check the <Modules.Facebook.permissions> property to make sure the user accepted the request for
additional permissions.
var fb = require('facebook');
fb.requestNewReadPermissions(['read_stream','user_hometown', etc...], function(e) {
if (e.success) {
fb.requestWithGraphPath(...);
} else if (e.cancelled) {
....
} else {
Ti.API.debug('Failed authorization due to: ' + e.error);
}
});
**Request Additional Write Permissions**
To request additional write permissions once the user authorizes your application, use the
[requestNewPublishPermissions()](Modules.Facebook.requestNewPublishPermissions) method.
Note that in addition to passing the permissions to request, you need to also pass an `AUDIENCE_*`
constant to indicate the default audience when positing content.
Check the <Modules.Facebook.permissions> property to make sure the user accepted the request for
additional permissions.
var fb = require('facebook');
fb.requestNewPublishPermissions(['read_stream','user_hometown', etc...], fb.AUDIENCE_FRIENDS, function(e) {
if (e.success) {
fb.requestWithGraphPath(...);
} else if (e.cancelled) {
....
} else {
Ti.API.debug('Failed authorization due to: ' + e.error);
}
});
### Share Dialogs
The Share dialog prompts a person to publish an individual story or an Open Graph story
to their timeline. This does not require the user to authorize your app or any extended permissions,
so it is the easiest way to enable sharing.
The Share dialog uses the Facebook apps interface, so the Facebook app needs to be installed. If
the Facebook app is not installed, the application can use the Feed dialog that presents the
dialog in a web-based view as a back up if the Share dialog is not available.
To present a Share dialog to a user, use the <Modules.Facebook.canPresentShareDialog> property to
check if the application can use the Share dialog. If the application supports the Share dialog,
call the [presentShareDialog()](Modules.Facebook.presentShareDialog) to present it, else call the
[presentWebShareDialog()](Modules.Facebook.presentWebShareDialog) method to present the Feed dialog.
Pass either method parameters you want to add to the post, such as a link or picture, or to
share the user's status, do not pass any parameters to the methods.
To monitor if the share request succeeded or not, listen to the <Modules.Facebook.shareCompleted>
event.
fb.addEventListener('shareCompleted', function (e) {
if (e.success) {
Ti.API.info('Share request succeeded.');
} else {
Ti.API.warn('Failed to share.');
}
});
fb.presentShareDialog({
link: 'https://appcelerator.com/',
title: 'great product',
description: 'Titanium is a great product',
picture: 'http://www.appcelerator.com/wp-content/uploads/scale_triangle1.png'
});
For details on the Share dialog, see the
[official Facebook Share Dialogs documentation](https://developers.facebook.com/docs/sharing/reference/share-dialog).
### Requests Dialog
A request dialog allows a user to invite another user to use your application.
Facebook will send a private message to the recipient.
The typical use case is to invite another user to play a game.
If you want to invite people to your application which is not a game, use the
[presentInviteDialog()](Modules.Facebook.presentInviteDialog) method instead.
To send a request to a user, call the
[presentSendRequestDialog()](Modules.Facebook.presentSendRequestDialog) method and pass the
method a dictionary with the `message` property set the message you want to send the invited user.
Optional: You can set the `title` property with a title string. You can also set the `data` property
with a dictionary of custom parameters. If you want to preselect users to send invite to, you can set
the `to` property with string of values that are facebook ids seperated by comma.
To monitor if the request succeeded or not, listen to the <Modules.Facebook.requestDialogCompleted> event.
fb.addEventListener('requestDialogCompleted', function (e) {
if (e.success) {
Ti.API.info('request succeeded.');
} else {
Ti.API.warn('Failed to share.');
}
});
fb.presentSendRequestDialog({
message: 'Go to https://appcelerator.com/',
title: 'Invitation to Appcelerator',
recipients: ['123456789', '123456788'],
data: {
badge_of_awesomeness: '1',
social_karma: '5'
}
});
For details on request dialogs see the
[official Facebook Request Dialogs documentation](https://developers.facebook.com/docs/games/requests/v2.2).
### Messenger Dialog
A messenger dialog allows a user to send content to the Facebook Messenger using your application.
To send a message to a user, call the [presentMessengerDialog()](Modules.Facebook.presentMessengerDialog) method
and pass the method a dictionary with the optional values "title", "description", "link", "to", "placeID"
and "referal".
fb.presentMessengerDialog({
title: "Appcelerator Titanium rocks!", // The title of the link
description: "Shared from my Titanium application", // The description of the link
link: "https://appcelerator.com", // The link you want to share
referal: "ti_app", // The referal to be added as a suffix to your link
placeID: "my_id", // The ID for a place to tag with this content
to: [] // List of IDs for taggable people to tag with this content
});
For details on dialog see the
[official Facebook Messenger Dialogs documentation](https://developers.facebook.com/docs/messenger).
### Messenger Button
The Messenger button provides a quick mechanism for users to share content to the Facebook Messenger.
A click on the button can share the content to multiple users.
To create a Messenger button, call the [createMessengerButton()](Modules.Facebook.createMessengerButton)
method and pass the "mode" and "style" properties:
var messengerButton = fb.createMessengerButton({
mode: fb.MESSENGER_BUTTON_MODE_RECTANGULAR
style: fb.MESSENGER_BUTTON_STYLE_BLUE
});
win.add(messengerButton);
For more information, see the [MessengerButton API reference](Modules.Facebook.MessengerButton).
### Like Button
The Like button provides a quick mechanism for users to share content. A click on the button
will share the content on the user's Facebook page.
To create a Like button, call the [createLikeButton()](Modules.Facebook.createLikeButton) method
and pass it a dictionary with the `objectID` assigned to either a URL or Open Graph object ID
you want to share. Add the button instance to a view to display it.
var likeButton = fb.createLikeButton({
objectID: "https://www.facebook.com/appcelerator"
});
win.add(likeButton);
For more information, see the [LikeButton API reference](Modules.Facebook.LikeButton).
extends: Titanium.Module
since: "3.1.0"
platforms: [android, iphone, ipad]
methods:
- name: authorize
summary: |
Prompts the user to log in (if not already logged in) and authorize your application.
You can also use [LoginButton](Modules.Facebook.LoginButton) to log in.
description: |
Be sure to set your required [permissions](Modules.Facebook.permissions) before
calling `authorize`.
A [login](Modules.Facebook.login) event is generated to indicate a successful or
unsuccessful login attempt.
#### iOS Platform Notes
On iOS, do not request any write permissions before calling this method. Use the
[requestNewPublishPermissions()](Modules.Facebook.requestNewPublishPermissions)
to request write permissions once the user authorizes the application.
#### Prior to Release 4.0.0
Set the [appid](Modules.Facebook.appid) property as well as the `permissions` property
before calling `authorize()`.
- name: createActivityWorker
summary: |
Creates a Facebook proxy to hook into the activity of either a standalone <Titanium.UI.Window>
(not inside a TabGroup) or <Titanium.UI.TabGroup>.
description: |
Set the `lifecycleContainer` property in the dictionary passed to the method to either
the current active instance of a <Titanium.UI.Window> or <Titanium.UI.TabGroup> in order to monitor the activity's
lifecycle events, required by Facebook to synchronize its state between various
activities in the application.
The proxy object must be created before calling the `open()` method on the associated Window
or TabGroup.
parameters:
- name: parameters
summary: |
Properties to set on a new object, including any defined by <Titanium.Proxy> except
those marked not-creation or read-only.
**Note:** You must set the `lifecycleContainer` property.
type: Dictionary<Titanium.Proxy>
returns:
type: Titanium.Proxy
since: 4.0.0
platforms: [android]
- name: dialog
summary: Opens a supported Facebook dialog.
deprecated:
since: 4.0.0
removed: 4.0.0
description: |
For a list of dialogs, parameters, and response formats, see the
[official documentation for Facebook Dialogs](https://developers.facebook.com/docs/javascript/reference/FB.ui).
The callback is invoked when the dialog is closed, either because the user
approved the action, or canceled the dialog.
parameters:
- name: action
summary: Specifies which dialog to show, such as "feed".
type: String
- name: params
summary: |
A dictionary object for pre-filling some of the dialog's fields.
type: Object
- name: callback
summary: Callback to invoke when the user completes or cancels the dialog.
type: Callback<FacebookDialogResponse>
- name: initialize
summary: |
Loads a cached Facebook session if available, then fires the `login` event.
description: |
Be sure to set your [login](Modules.Facebook.login) and [logout](Modules.Facebook.logout)
event listeners before calling `initialize`.
deprecated:
since: 5.0.0
parameters:
- name: timeout
summary: Sets initialize timeout in milliseconds.
type: Number
since: 4.0.0
- name: logCustomEvent
summary: Logs a custom event to Facebook.
description: |
**From the Facebook API Reference:**
Events are not sent immediately when logged. They're cached and flushed out to the Facebook servers
in a number of situations:
* when an event count threshold is passed (currently 100 logged events).
* when a time threshold is passed (currently 15 seconds).
* when an app has gone to background and is then brought back to the foreground.
Some things to note when logging events:
* There is a limit on the number of unique event names an app can use, on the order of 300.
* Event names must be between 2 and 40 characters and must consist of alphanumeric
characters, `_`, `-` or spaces.
parameters:
- name: event
summary: Arbitrary string to log as an event.
type: String
- name: valueToSum
summary: |
An arbitrary number that can represent any value (e.g., a price or a quantity).
When reported, all of the valueToSum properties will be summed together in Facebook Analytics for Apps.
type: Number
optional: true
since: "5.4.0"
- name: params
summary: |
A dictionary object containing optional parameters.
type: Object
optional: true
since: "5.4.0"
since: "4.0.0"
- name: logPurchase
summary: Log a purchase of the specified amount, in the specified currency.
parameters:
- name: amount
summary: |
Purchase amount to be logged, as expressed in the specified currency.
This value will be rounded to the thousandths place (e.g., 12.34567 becomes 12.346).
type: Number
- name: currency
summary: |
Currency, is denoted as, e.g. "USD", "EUR", "GBP". See ISO-4217 for specific values.
type: String
since: "5.2.0"
- name: logout
summary: Clears the OAuth `accessToken` and logs out the user.
- name: publishInstall
deprecated:
since: 4.0.0
removed: 4.0.0
summary: |
Manually publish an attributed install to the facebook graph.
description: |
Be sure to set your [appid](Modules.Facebook.appid) before calling `publishInstall`.
since: "3.4.1"
- name: presentInviteDialog
summary: |
Opens a supported Facebook Invite dialog from the Facebook App.
description: |
To monitor if the share request succeeded or not, listen to the
<Modules.Facebook.shareCompleted> event.
parameters:
- name: params
summary: |
A dictionary object containing required and optional parameters.
type: InviteDialogParams
since: "5.4.0"
platforms: [iphone, ipad, android]
- name: presentShareDialog
summary: |
Opens a supported Facebook Share dialog from the Facebook App.
description: |
Be sure to check if the device can support this method by calling [getCanPresentShareDialog](Modules.Facebook.getCanPresentShareDialog)
before using this method. If true, you can use this method. If false, the Facebook application
is probably not installed in the device. In this case, use [presentWebShareDialog](Modules.Facebook.presentWebShareDialog)
instead.
Listen for the <Modules.Facebook.shareCompleted> to be notified if the attempt was
successful or not.
parameters:
- name: params
summary: |
A dictionary object containing optional parameters.
type: ShareDialogParams
since: 4.0.0
- name: presentMessengerDialog
summary: |
Opens a supported Messenger dialog from the Facebook Messenger App.
description: |
Be sure to check if the device can support this method by calling [canOpenURL](Titanium.Platform.canOpenURL) with "fb-messenger-api://"
before using this method. If true, you can use this method. If false, the Facebook Messenger application
is probably not installed in the device.
Listen for the <Modules.Facebook.shareCompleted> to be notified if the attempt was
successful or not.
parameters:
- name: params
summary: |
A dictionary object containing optional parameters.
type: MessengerDialogParams
since: "5.4.0"
platforms: [iphone, ipad]
- name: presentWebShareDialog
summary: |
Opens a web version of the Share dialog (Feed dialog). Does not depend on the Facebook app.
description: |
This is a fallback for when Share dialog is not available.
Listen for the <Modules.Facebook.shareCompleted> to be notified if the attempt was
successful or not.
parameters:
- name: params
summary: |
A dictionary object containing optional parameters.
type: ShareDialogParams
since: 4.0.0
deprecated:
since: 5.0.0
removed: 5.0.0
- name: presentSendRequestDialog
summary: |
Opens an App Request dialog.
description: |
A `requestDialogCompleted` event is generated to indicate if the request attempt was successful or unsuccessful,
and the resultURL.
parameters:
- name: params
summary: |
A dictionary object containing parameters.
type: RequestDialogParams
since: 4.0.0
- name: reauthorize
summary: Makes a request to Facebook for additional permissions.
deprecated:
since: 4.0.0
removed: 4.0.0
description: |
iOS 6's facebook login forbids minimum authorization to include write permissions.
In order to make any write actions, the app must reauthorize asking for the additional
permissions. If the application already has these permissions, there will be no user
interaction.
platforms: [iphone, ipad]
parameters:
- name: permissions
summary: |
Array of additional permissions to request. For a complete list of permissions, see the
[official Facebook Permissions Reference](http://developers.facebook.com/docs/reference/api/permissions/)
type: Array<String>
- name: audience
summary: |
The extent of the visibility write permissions will have.
The value of audience should be one of "me", "friends", or "everyone"
type: String
- name: callback
summary: Callback to invoke when the request completes.
type: Callback<FacebookReauthResponse>
- name: refreshPermissionsFromServer
summary: Makes a request to Facebook to get the latest permissions granted.
description: |
Facebook now grants total control over granted permissions, and if the user modified the permissions
outside of your app your cached token may not be updated.
Listen for the <Modules.Facebook.tokenUpdated> event to be notified if the attempt was
successful.
since: 4.0.0
- name: request
summary: Makes a request to the legacy Facebook REST API.
deprecated:
since: 4.0.0
removed: 4.0.0
notes: |
As of April 30, 2014, Facebook no longer supports its version 1.0 REST API. Use the
<Modules.Facebook.requestWithGraphPath> method to make Facebook Graph API requests.
description: |
For details on API calls and responses, see the
[offical Facebook REST API documentation](http://developers.facebook.com/docs/reference/rest/).
parameters:
- name: method
summary: The REST API method to call.
type: String
- name: params
summary: |
A dictionary object for setting parameters required by the call, if any.
type: Object
- name: callback
summary: Callback to invoke when the request completes.
type: Callback<FacebookRESTResponse>
- name: requestWithGraphPath
summary: Makes a Facebook Graph API request.
description: |
If the request requires user authorization, the user must be logged in, and your app
must be authorized to make the request. You can check the
[loggedIn](Modules.Facebook.loggedIn) property to determine if the user is logged in.
Every Facebook object has an associated path. For example, "me" requests information about
the current user.
For a complete list of Graph API methods, parameters and return types, see the
[official Facebook Graph API documentation](https://developers.facebook.com/docs/graph-api).
parameters:
- name: path
summary: Graph API path to request.
type: String
- name: params
summary: |
A dictionary object for setting parameters required by the call, if any.
type: Dictionary
- name: httpMethod
summary: The HTTP method (GET/POST/DELETE) to use for the call.
type: String
- name: callback
summary: Callback to invoke when the request completes.
type: Callback<FacebookGraphResponse>
- name: requestNewReadPermissions
summary: Makes a request to Facebook for additional read permissions.
description: |
Note that it is not an error for the user to 'Skip' your requested permissions,
so you should check the module's `permissions` property following the call.
parameters:
- name: permissions
summary: |
Array of additional permissions to request. For a complete list of permissions, see the
[official Facebook Permissions Reference](https://developers.facebook.com/docs/facebook-login/permissions/v2.2)
type: Array<String>
- name: callback
summary: Callback to invoke when the request completes.
type: Callback<FacebookPermissionResponse>
since: 4.0.0
- name: requestNewPublishPermissions
summary: Makes a request to Facebook for additional write permissions.
description: |
Note that it is not an error for the user to 'Skip' your requested permissions,
so you should check the module's `permissions` property following the call.
parameters:
- name: permissions
summary: |
Array of additional permissions to request. For a complete list of permissions, see the
[official Facebook Permissions Reference](https://developers.facebook.com/docs/facebook-login/permissions/v2.2)
type: Array<String>
- name: audience
summary: |
The extent of the visibility write permissions will have.
type: Number
constants: Modules.Facebook.AUDIENCE_*
- name: callback
summary: Callback to invoke when the request completes.
type: Callback<FacebookPermissionResponse>
since: 4.0.0
- name: fetchDeferredAppLink
summary: Fetch the deferred app link
description: Deferred deep linking allows you to send people to a custom view after they installed your app via the app store.
parameters:
- name: callback
summary: Callback to invoke when the request completes.
type: Callback<FacebookDeferredAppLinkResponse>
since: "5.4.0"
- name: shareMediaToMessenger
summary: Call this method to open Messenger and share an image, animated GIF or video.
parameter:
- name: params
summary: |
A dictionary object containing required and optional parameters.
type: ShareToMessengerParams
since: "5.4.0"
platforms: [iphone, ipad]
events:
- name: login
summary: Fired at session login.
properties:
- name: success
summary: |
Indicates if the user was logged in successfully.
Returns `true` if request succeeded, `false` otherwise.
type: Boolean
- name: cancelled
summary: |
Indicates if the user canceled the login request by closing the dialog.
type: Number
- name: error
summary: |
Error message, if any returned.
Will be undefined if `success` is `true`.
type: String
- name: code
summary: |
Error code.
Error code will be 0 if `success` is `true`, nonzero otherwise. If the error
was generated by the operating system, that system's error value is used.
Otherwise, this value will be -1.
type: Number
- name: uid
summary: User ID returned by Facebook if the login was successful.
type: String
- name: data
summary: |
Data returned by Facebook when we query for the UID (using graph path "me")
after a successful login. Data is in JSON format, and includes information
such as user name, locale and gender.
- name: logout
summary: Fired at session logout.
- name: requestDialogCompleted
summary: Fired when the Send Request dialog is closed.
properties:
- name: success
summary: |
Returns `true` if request succeeded, `false` otherwise.
type: Boolean
- name: cancelled
summary: |
Indicates if the user canceled the request by closing the dialog.
type: Number
- name: error
summary: |
Error message, if any returned.
Will be undefined if `success` is `true`.
type: String
- name: data
summary: |
data returned by Facebook. See Facebook reference for details.
type: Dictionary
since: 4.0.2
- name: shareCompleted
summary: Fired when the Share dialog or Web Share dialog is closed.
properties:
- name: success
summary: |
Returns `true` if request succeeded, `false` otherwise.
type: Boolean
- name: cancelled
summary: |
Indicates if the user canceled the request by closing the dialog.
type: Number
- name: error
summary: |
Error message, if any returned.
Will be undefined if `success` is `true`.
type: String
since: 4.0.0
- name: inviteCompleted
summary: Fired when the Invite dialog is closed.
properties:
- name: success
summary: |
Returns `true` if request succeeded, `false` otherwise.
type: Boolean
- name: cancelled
summary: |
Indicates if the user canceled the request by closing the dialog.
type: Number
- name: error
summary: |
Error message, if any returned.
Will be undefined if `success` is `true`.
type: String
since: 5.4.0
- name: tokenUpdated
summary: Fired when [refreshPermissionsFromServer](Modules.Facebook.refreshPermissionsFromServer) is completed.
since: 4.0.0
properties:
- name: AUDIENCE_NONE