October 1, 2014

US-only Gray User Login Deprecation

Documentation:

• https://developers.facebook.com/docs/reference/ads-api/businessmanager-systemuser
• https://developers.facebook.com/docs/reference/ads-api/businessmanager/
• https://developers.facebook.com/docs/reference/ads-api/sharedlogin-migration
• Create a Business Manager
• Best Practices for PMDs

A “gray user account” also known as a “shared login” or “business account” is a type of Facebook account that does not have a real user profile. Gray user accounts are used by some advertisers to manage multiple Facebook ad accounts, Pages or to use Facebook's APIs. Creating gray user accounts has historically been a manual and time consuming process requiring assistance from internal Facebook teams. As a result of this feedback, we have created a self-service solution called Business Manager for business level management of ad accounts, Pages, and permissions that no longer require you to create gray user accounts.

Business Manager can help you organize and manage all of the ad accounts and pages for your businesses. Business Manager is a new level of organization on top of existing assets that offers the following benefits:

• Work faster and better so it's easier to grow your business

  • Reduce the time it takes to set up and manage your ad accounts and Pages
  • Create new ad accounts on demand
  • Directly request roles on client pages
• Everything in one place

  • Use Business.facebook.com to see and manage all your Facebook Pages and ad accounts
  • Give people in your Business Manager access without sharing usernames or passwords
• Increased control

  • Clearly see who has access to your Pages and ad accounts
  • Easily remove or change who has permission to access your Pages and ad accounts

Business Manager is free to use and it does not replace the existing management tools of ads manager, Pages Manager, Power Editor, or third party tools. These are still used to manage individual pages or ad accounts within a business manager. Existing APIs for managing these are also unchanged. Business Manager adds a layer of organization on top of these assets and tools to help you scale your business.

LEARN MORE ABOUT BUSINESS MANAGER: https://business.facebook.com/overview

Important Dates

Two dates will impact customers who use gray accounts

As of August 1st, Facebook will no longer create new gray user logins for customers in the US. All new ad accounts must be created through Business Manager.

As of October 1st, Facebook will no longer support login requests from gray users in the US.

Note: these dates apply to any advertiser or PMD who manages gray accounts in the US. However, we encourage all PMDs to review the API documentation to prepare for the upcoming changes. As we continue to scale Business Manager, we will notify you of the corresponding rollout dates for international markets.

Actions needed prior to August 1st

If you need new accounts to create and manage ads after August 1st, you will need to use the Business Manager UI or the Business Manager API to create your own ad accounts. Note that existing gray users will continue to function as before until October 1st. There will be no change in functionality to your existing gray users, gray user API tokens, or the ad accounts and Pages they manage.

Actions needed prior to October 1st

As of October 1st, gray user logins will no longer be supported, and assets that are managed or owned by gray users must be migrated to Business Manager to avoid service interruption. No Pages or ad accounts will be deleted as part of this change and ads will continue to run. However, you must arrange to have gray user assets managed using Business Manager prior to October 1st as the gray user login will not be allowed to log in to the account for management and tokens will no longer be granted. Migration of assets from a gray user to a business manager also does not cause service interruption or change in any of the assets.

After October 1st, Facebook will continue offer a UI to migrate assets to Business Manager for an additional 90 days, but tokens will not be issued and content and ad creation operations will not be permitted until after migration to Business Manager.

Step by step

1. Check if your accounts are gray user accounts:

Using the API, calling FQL “/me” with a gray user returns data as below without a Name field, as below: (regular user accounts will have a Name attribute)

{
 "id": "[14******************25](https://graph.facebook.com/1433037676971325)", 
 "link": "[https://www.facebook.com/app_scoped_user_id/](https://www.facebook.com/app_scoped_user_id/1433037676971325/)[14******************25](https://graph.facebook.com/1433037676971325)/", 
 "locale": "en_US", 
 "timezone": -7, 
 "updated_time": "2014-03-05T23:11:03+0000", 
 "verified": false
 }

Or from a browser:

Log in to Facebook.com with the username and password of the gray account. When you log in to Facebook with a gray account using a desktop web browser, you are taken immediately to an ad account or a Page instead of seeing a Facebook News Feed. We will be releasing an additional API on Aug 1 to query the deprecation date for each gray user account.

2. Setup your Business Manager

Learn about business manager from https://business.facebook.com/overview then follow the steps at http://business.facebook.com/create to setup your Business Manager. You must be signed in as a real Facebook user to complete Business Manager setup.

3. Migrate any assets from your gray users into your Business Manager

Following the steps outlined here: https://developers.facebook.com/docs/reference/ads-api/sharedlogin-migration Ensure that your Business Manager owns the assets you need after migration and assign them to people within your Business Manager as needed.

4. Replace gray user tokens embedded in your API before October 1st

For customers using gray user tokens to all Facebook APIs, Business Manager offers an improved solution to support applications calling Facebook's APIs with a new mechanism called System Users. Once your Business Manager is setup, ensure that your applications are claimed into your Business Manager. Follow steps outlined here for further details on system users. For applications with Ads API access you’ll be able to see a special pane in Business Manager where you can create System Users.

5. Review messaging US clients will receive from Facebook

Facebook's sales teams will be reaching out to their US clients to notify them of the gray account deprecation dates. Please find guidelines for client outreach here.

New Graph API framework conversion

Migrate Ads API endpoints to new Graph API framework for Q4 2014
Documentation: https://developers.facebook.com/docs/reference/ads-api/adaccount/
https://developers.facebook.com/docs/reference/ads-api/custom-audience-targeting/

For the following endpoints, OAuthInsufficientScopeException will now be replaced by a GraphMethodException. count, offset, limit will no longer be returned and you must instead use a cursor-based approach to paging. Finally, total_count is only returned when the flag summary=true is set.

• Ad account GET
• Custom Audiences GET

Ad account GET

https://graph.facebook.com/act_{ad_account_id}

• New field: created_time which is the time the account was created
• funding_source now returns a numeric string ID
• users now returns a data property with fields id, permissions, and role (id instead of uid)
• account_group_id value within account_groups now returns a numeric string ID

Example of changes:

https://graph.facebook.com/act_{ad_account_id}?fields=created_time,funding_source,users

{
  "created_time": "2008-12-08T14:26:23-0800", 
  "funding_source": "962324027801", 
  "users": {
    "data": [
      {
        "id": "594012385", 
        "permissions": [
          1, 
          2, 
          3, 
          4, 
          5, 
          7
        ], 
        "role": 1001
      }
    ]
  }, 
  "account_id": "{ad_account_id}", 
  "id": "act_{ad_account_id}"
}

Custom Audiences GET

GET https://graph.facebook.com/act_{ad_account_id}/customaudiences
and
GET https://graph.facebook.com/{audience_id}

Removal of following fields:

• parent_audience_id
• parent_category
• status, use delivery_status or operation_status
• type
• type_name

Previously, these fields would return null or a single value, so are being removed for simplicity.

Addition of following fields:

• data_source
• delivery_status
• operation_status
• permission_for_actions

See the documentation for explanation of new fields.

Changes to following fields:

• account_id type change from int to numeric string ID
• id type change from int to numeric string ID

Previously all fields were returned by default, now you must explicity request them.

Example of changes to GET https://graph.facebook.com/act_{ad_account_id}/customaudiences:

// Fields need to be explicitly requested
https://graph.facebook.com/act_{ad_account_id}/customaudiences

{
  "data": [
    {
      "id": "{audience_id}"
    }, 
  ], 
  "paging": {
    "cursors": {
      "before": "TmpBeE56azBNakF4TmpNME9Eb3hOREF6TWpnMk1qQXpPakkwTnpJNE5URXpNakEyT1RFeU1BPT0=", 
      "after": "TmpBd09UZ3dORGszTlRrME9Eb3hNell3T0Rnd05qZ3dPakkwTnpJNE5URXpNakEyT1RFeU1BPT0="
    }
  }
}

// Example for new field responses
https://graph.facebook.com/act_{ad_account_id}/customaudiences?fields=account_id,approximate_count,lookalike_audience_ids,lookalike_spec,name,parent_audience_id,parent_category,status,subtype,type,type_name,time_updated,operation_status,delivery_status,permission_for_actions,data_source

{
  "data": [
    {
      "account_id": "{ad_account_id}", 
      "approximate_count": 20, 
      "lookalike_spec": {
        "country": "US", 
        "origin": [
          {
            "id": "{source_id}", 
            "name": "my page", 
            "type": "page"
          }
        ], 
        "ratio": 0.01, 
        "type": "custom_ratio"
      }, 
      "name": "My Audience", 
      "subtype": "APP", 
      "time_updated": 1381276042, 
      "data_source": {
        "type": "SEED_BASED", 
        "sub_type": "PAGE_FANS", 
        "creation_params": "[]"
      }, 
      "delivery_status": {
        "code": 200, 
        "description": "This audience is ready for use."
      }, 
      "operation_status": {
        "code": 200, 
        "description": "Normal"
      }, 
      "permission_for_actions": {
        "can_edit": true, 
        "can_see_insight": true, 
        "can_share": false, 
        "subtype_supports_lookalike": true
      }, 
      "id": "{audience_id}"
    }
  ], 
  "paging": {
    "cursors": {
      "before": "TmpBeE1qVXdNekEwTlRVME9Eb3hNemd4TWpjMk1EUXpPakkwTnpJNE5URXpNakEyT1RFeU1BPT0=", 
      "after": "TmpBeE1qVXdNekEwTlRVME9Eb3hNemd4TWpjMk1EUXpPakkwTnpJNE5URXpNakEyT1RFeU1BPT0="
    }
  }
}

Example of changes to GET https://graph.facebook.com/{audience_id}:

// Fields need to be explicitly requested
https://graph.facebook.com/{audience_id}

{
  "id": "{audience_id}"
}

// Example for new field responses
https://graph.facebook.com/{audience_id}?fields=account_id,approximate_count,lookalike_audience_ids,lookalike_spec,name,subtype,time_updated,operation_status,delivery_status,permission_for_actions,data_source

{
  "account_id": "{ad_account_id}", 
  "approximate_count": 20, 
  "lookalike_spec": {
    "country": "US", 
    "origin": [
      {
        "id": "{source_id}", 
        "name": "my page", 
        "type": "page"
      }
    ], 
    "ratio": 0.01, 
    "type": "custom_ratio"
  }, 
  "name": "First-time purchaser - over five dollars", 
  "subtype": "APP", 
  "time_updated": 1381276042, 
  "operation_status": {
    "code": 200, 
    "description": "Normal"
  }, 
  "delivery_status": {
    "code": 300, 
    "description": "Audiences must include at least 20 people to be used for ads."
  }, 
  "permission_for_actions": {
    "can_edit": true, 
    "can_see_insight": true, 
    "can_share": false, 
    "subtype_supports_lookalike": true
  }, 
  "data_source": {
    "type": "SEED_BASED", 
    "sub_type": "PAGE_FANS", 
    "creation_params": "[]"
  }, 
  "id": "{audience_id}"
}

Deleted/Archive status

Adding the Archived status to Ads objects

Documentation: http://developers.facebook.com/docs/ads-api/best-practices/storing_adobjects

Previously, the loading of deleted adgroups/adset/adcampaigns sometimes threw exceptions. To address this problem we introduced two (2) types of delete states, archived and deleted, for all ad objects. You can query objects in both archived and deleted state based on the object id, however deleted objects will not be available for retrieval via the connection objects.

For archived state you can have up to 50,000 objects, hence you need to move ad objects from archived state to deleted state once there is no need to retrieve from the edges. To get a better understanding of how the migration works and api calls, see this migration and best practice document.

Ad Group Breaking Change
Ad Set Breaking Change
Ad Campaign Breaking Change

Custom Audiences API v2

Migration name: Custom Audience New Upload API

Documentation: https://developers.facebook.com/docs/reference/ads-api/custom-audience-targeting/

Migration applies to GET, POST, DELETE https://graph.facebook.com/{audience_id}/users

Adding/removing users from Custom Audiences will have a simpler upload format:

The users field from the https://graph.facebook.com/{audience_id}/users endpoint will be deprecated in favor of payload. Details of the payload field provided in Adding People to Audiences.

curl \
-F 'payload = { \ 
"schema":"EMAIL_SHA256", \
"data":["HASH", "HASH", "HASH"]}' \
-F "access_token=_____" \
"https://graph.facebook.com/6005123456/users"

MD5 hashing will no longer be supported. For hashing fields, use SHA-256.

There are changes to the schema names when specifying the type of data:

The response to adding users to an audience will contain the following fields instead of returning true:

Rename custom audiences from your website remarketingpixelcode endpoint

Migration name: Deprecate /act_xxx/remarketingpixelcode endpoint

Documentation: https://developers.facebook.com/docs/reference/ads-api/custom-audience-website

The /remarketingpixelcode endpoint for receiving the Custom Audience Pixel code is going to be renamed to /adspixels so that in the future it can be more easily generalized. This endpoint will be used both for creating the Custom Audience pixel and for reading the pixel code. We plan to add more features to this endpoint in the future.

Structured targeting sentences

Documentation: https://developers.facebook.com/docs/reference/ads-api/targeting-description

https://graph.facebook.com/{adgroup_id or adaccountid}/targetingsentencelines will now return a JSON structured response instead of a JSON string array.

**Before**

 "targetingsentencelines": [
    "Location: Japan; United States",
    "Age: 20 - 24",
    "Gender: male"
 ]


**After**

 "targetingsentencelines": [
    {
       "content": "Location:",
       "children": [
          "Japan",
          "United States"
       ]
    },
    {
       "content": "Age:",
       "children": [
          "20 - 24"
       ]
    },
    {
       "content": "Gender:",
       "children": [
          "male"
       ]
    }
 ]

Generalize vat_status field of ad account into tax_id_status

Documentation: https://developers.facebook.com/docs/reference/ads-api/adaccount

The field vat_status will be renamed tax_id_status to allow for a more general usage in the future.

curl http://graph.facebook.com/act_{account_id}?fields=tax_id_status
{
  "tax_id_status": 1, 
  "account_id": "{account_id}", 
  "id": "act_{account_id}"
}