Advanced Uses

Audience Targeting

Include and exclude specific audiences from viewing your Live Video.

Create a Target Audience

Node

• LiveVideo

Before You Start

For live videos on a Page, you will need:

• A Page access token requested by a person who can perform the CREATE_CONTENT task on the Page
• The pages_read_user_content permission
• The pages_manage_engagement permission
• The pages_show_list permission
• The publish_video permission

For live videos in a Group, you will need:

• A User access token requested by an admin of the Group
• The publish_video permission

Examples

Send a POST /id request where id is the LiveVideo ID and set the targeting field and its parameters.

curl -i -X POST \
  "https://graph.facebook.com/LIVE_VIDEO_ID
    ?targeting={age_min:17, geo_locations:{countries:["US","CA","MX"]}}
    &access_token=ACCESS_TOKEN"

GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/LIVE_VIDEO_ID/",
  new JSONObject("{}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();

FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/LIVE_VIDEO_ID/"
           parameters:@{ @"targeting": @"{age_min:17, geo_locations:{countries:["US","CA","MX"]}, excluded_zipcodes:{"key":"US:10001"}}",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];

FB.api(
  '/LIVE_VIDEO_ID/',
  'POST',
  {"targeting":"{age_min:17, geo_locations:{countries:[\"US\",\"CA\",\"MX\"]}, excluded_zipcodes:{\"key\":\"US:10001\"}}"},
  function(response) {
      // Insert your code here
  }
);

try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/LIVE_VIDEO_ID/',
    array (
      'targeting' => '{age_min:17, geo_locations:{countries:["US","CA","MX"]}, excluded_zipcodes:{"key":"US:10001"}}'
    ),
    'ACCESS_TOKEN'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Sample Response

{
  "targeting": {
    "age_max": 65,
    "age_min": 17,
    "geo_locations": {
      "countries": [
        "US",
        "CA",
        "MX"
      ]
    }
  },
  "id": "LIVE_VIDEO_ID"   
}

Get Target Audience Information

Node

• LiveVideo

Before You Start

For live videos on a Page, you will need:

• A Page access token requested by a person who can perform the CREATE_CONTENT task on the Page
• The pages_read_engagement permission
• The pages_show_list permission

For live videos on a Group, you will need:

• A User access token requested by an admin of the group

Examples

Send a GET /id request where id is the LiveVideo ID with the targeting field.

GraphRequest request = GraphRequest.newGraphPathRequest(
  accessToken,
  "/LIVE_VIDEO_ID",
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

Bundle parameters = new Bundle();
parameters.putString("fields", "targeting");
request.setParameters(parameters);
request.executeAsync();

FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/LIVE_VIDEO_ID"
           parameters:@{ @"fields": @"targeting",}
           HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];

FB.api(
  '/LIVE_VIDEO_ID',
  'GET',
  {"fields":"targeting"},
  function(response) {
      // Insert your code here
  }
);

try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->get(
    '/LIVE_VIDEO_ID',
    'ACCESS_TOKEN'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

curl -i -X GET \
  "https://graph.facebook.com/LIVE_VIDEO_ID
    ?fields=targeting&access_token=ACCESS_TOKEN"

Sample Response

{
  "targeting": {
    "age_max": 65,
    "age_min": 17,
    "geo_locations": {
      "countries": [
        "US"
        "CA",
        "MX"
      ]
    }
  },
  "id": "LIVE_VIDEO_ID"       
}

Frame-Accurate Go-Live

There can be a slight delay before a broadcast goes live while we decode its initial streaming data and process any associated API requests. This can make it difficult for on-air talent to know exactly when a broadcast has started. To avoid this problem, LiveVideo objects can be set to accept streaming data but to not go live to audiences until a go-live RTMP message is detected within the streaming data itself. This allows anyone who is able to preview a broadcast to see it, while allowing the streaming encoder to precisely control both the time at which the broadcast goes live for an audience and the first frame that the audience sees.

To enable frame-accurate go-live, first create a LiveVideo object as you normally would and set its status to PREVIEW. Once it has been created, query the LiveVideo object and request the secure_stream_url field with the following nested fields:

secure_stream_url.inband_go_live(require_inband_signal)

This will enable frame-accurate go-live on the LiveVideo object and the API will respond with a new secure stream URL which you can then stream to. You can disregard the initial secure stream url that was sent to you when you first created the LiveVideo object.

The broadcast will go live and be visible to the audience after (1) the broadcast status is set to LIVE (through a Graph API call or a user publishing from Live Producer) and (2) the encoder sends the go-live RTMP message.

Go-Live RTMP Message Structure

An AMF0 packet (type 0x12) containing:

• the string onGoLive
• an ECMA array (type 0x08) containing a single key-value pair:
  • Key: string (type 0x02) timestamp
  • Value: number (type 0x00): the timestamp of the first video frame that will be publicly visible

For more information, see the RTMP and AMF0 specifications.

Sample Request

Sample request to enable frame-accurate go-live on a LiveVideo.

curl -i -X GET \
   "https://graph.facebook.com/v19.0/LIVE_VIDEO_ID?fields=secure_stream_url.inband_go_live(require_inband_signal)&access_token=12345..."

Sample Response

Secure stream URL for a LiveVideo object with frame-accurate go-live enabled.

{
  "secure_stream_url": "rtmps://rtmp-pc.facebook.com:443/rtmp/LIVE_VIDEO_ID?s_bl=1&s_gl=1&...",
  "id": "LIVE_VIDEO_ID"
}

Go Live Dialog

We've created a plugin to make the process of Live API integration as easy as possible enabling you to authenticate with Facebook, preview your live stream, and describe your live stream through a pop-up window before going live. This dialog is best suited for those streaming from the client side. Backend integrations should continue to use the API directly.

Requirements

• The Facebook SDK for Javascript must be implemented in either a browser (website) or WebView (desktop app).

To initialize a pop-up window with controls that determine where to direct your POST response insert the following code.

<button id="liveButton">Create Live Stream To Facebook</button>
<script>
document.getElementById('liveButton').onclick = function() {
  FB.ui({
    display: 'popup',
    method: 'live_broadcast',
    phase: 'create',
}, function(response) {
    if (!response.id) {
      alert('dialog canceled');
      return;
    }
    alert('{your-stream-url}:' + response.secure_stream_url);
    FB.ui({
      display: 'popup',
      method: 'live_broadcast',
      phase: 'publish',
      broadcast_data: response,
    }, function(response) {
    alert("video status: \n" + response.status);
    });
  });
};
</script>

In the Create phase pop-up window, choose the live stream destination which can be on any pages or groups you manage. The POST response will include the stream_url and secure_stream_url fields. Either one can be broken out into a server URL and stream key.

The server URL is the first half of the stream_url: rtmp://rtmp-api.facebook.com:80/rtmp/

The stream key is the latter half of the stream_url: 10153307708286557?ds=1&a=AdrRKk4mOaqPbQdxDuk

In our code snippet, we have an alert call with the stream_url. Your client should start streaming using stream_url. Soon after the stream starts, you will notice a preview of the broadcast appear in the publish phase pop-up window. The dialog enables users to choose privacy settings without adjusting the request's privacy parameter and to set the Live video description, title, and topic tags.

Note: If the publish pop-up window is Offline, ensure that your firewall is not blocking RTMP and that any Adblocker software on your browser is turned off.

When you click Go Live, the dialog will close and within a few seconds, the live stream play on the page or group, according to the chosen destination.

Metadata is injected into the first frame of a live video with frame-accurate start times. Encoders can implement a countdown to alert publishers to the exact start of the video. You can also start and stop the video from the Facebook interface.