facebook_business/adobjects/helpers/customaudiencemixin.py

# Copyright 2014 Facebook, Inc.

# You are hereby granted a non-exclusive, worldwide, royalty-free license to
# use, copy, modify, and distribute this software in source code or binary
# form for use in connection with the web services and APIs provided by
# Facebook.

# As with any software that integrates with the Facebook platform, your use
# of this software is subject to the Facebook Developer Principles and
# Policies [http://developers.facebook.com/policy/]. This copyright notice
# shall be included in all copies or substantial portions of the software.

# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
# DEALINGS IN THE SOFTWARE.

from facebook_business.exceptions import FacebookBadObjectError

import hashlib
import six
import re

class CustomAudienceMixin:

    class Schema(object):
        uid = 'UID'
        email_hash = 'EMAIL_SHA256'
        phone_hash = 'PHONE_SHA256'
        mobile_advertiser_id = 'MOBILE_ADVERTISER_ID'

        class MultiKeySchema(object):
            extern_id = 'EXTERN_ID'
            email = 'EMAIL'
            phone = 'PHONE'
            gen = 'GEN'
            doby = 'DOBY'
            dobm = 'DOBM'
            dobd = 'DOBD'
            ln = 'LN'
            fn = 'FN'
            fi = 'FI'
            ct = 'CT'
            st = 'ST'
            zip = 'ZIP'
            madid = 'MADID'
            country = 'COUNTRY'
            appuid = 'APPUID'

    @classmethod
    def format_params(cls,
                      schema,
                      users,
                      is_raw=False,
                      app_ids=None,
                      pre_hashed=None,
                      session=None):
        hashed_users = []
        if schema in (cls.Schema.phone_hash,
                      cls.Schema.email_hash,
                      cls.Schema.mobile_advertiser_id):
            for user in users:
                if schema == cls.Schema.email_hash:
                    user = user.strip(" \t\r\n\0\x0B.").lower()
                if isinstance(user, six.text_type) and not(pre_hashed) and schema != cls.Schema.mobile_advertiser_id:
                    user = user.encode('utf8')  # required for hashlib
                # for mobile_advertiser_id, don't hash it
                if pre_hashed or schema == cls.Schema.mobile_advertiser_id:
                    hashed_users.append(user)
                else:
                    hashed_users.append(hashlib.sha256(user).hexdigest())
        elif isinstance(schema, list):
            # SDK will support only single PII
            if not is_raw:
                raise FacebookBadObjectError(
                    "Please send single PIIs i.e. is_raw should be true. " +
                    "The combining of the keys will be done internally.",
                )
            # users is array of array
            for user in users:
                if len(schema) != len(user):
                    raise FacebookBadObjectError(
                        "Number of keys in each list in the data should " +
                        "match the number of keys specified in scheme",
                    )
                    break

                # If the keys are already hashed then send as it is
                if pre_hashed:
                    hashed_users.append(user)
                else:
                    counter = 0
                    hashed_user = []
                    for key in user:
                        key = key.strip(" \t\r\n\0\x0B.").lower()
                        key = cls.normalize_key(schema[counter],
                                                           str(key))
                        if schema[counter] != \
                                cls.Schema.MultiKeySchema.extern_id:
                            if isinstance(key, six.text_type):
                                key = key.encode('utf8')
                            key = hashlib.sha256(key).hexdigest()
                        counter = counter + 1
                        hashed_user.append(key)
                    hashed_users.append(hashed_user)

        payload = {
            'schema': schema,
            'is_raw': is_raw,
            'data': hashed_users or users,
        }

        if schema == cls.Schema.uid:
            if not app_ids:
                raise FacebookBadObjectError(
                    "Custom Audiences with type " + cls.Schema.uid +
                    "require at least one app_id",
                )

        if app_ids:
            payload['app_ids'] = app_ids

        params = {
            'payload': payload,
        }
        if session:
            params['session'] = session
        return params

    @classmethod
    def normalize_key(cls, key_name, key_value=None):
        """
            Normalize the value based on the key
        """
        if key_value is None:
            return key_value

        if(key_name == cls.Schema.MultiKeySchema.extern_id or
           key_name == cls.Schema.MultiKeySchema.email or
           key_name == cls.Schema.MultiKeySchema.madid or
           key_name == cls.Schema.MultiKeySchema.appuid):
            return key_value

        if(key_name == cls.Schema.MultiKeySchema.phone):
            key_value = re.sub(r'[^0-9]', '', key_value)
            return key_value

        if(key_name == cls.Schema.MultiKeySchema.gen):
            key_value = key_value.strip()[:1]
            return key_value

        if(key_name == cls.Schema.MultiKeySchema.doby):
            key_value = re.sub(r'[^0-9]', '', key_value)
            return key_value

        if(key_name == cls.Schema.MultiKeySchema.dobm or
           key_name == cls.Schema.MultiKeySchema.dobd):

            key_value = re.sub(r'[^0-9]', '', key_value)
            if len(key_value) == 1:
                key_value = '0' + key_value
            return key_value

        if(key_name == cls.Schema.MultiKeySchema.ln or
           key_name == cls.Schema.MultiKeySchema.fn or
           key_name == cls.Schema.MultiKeySchema.ct or
           key_name == cls.Schema.MultiKeySchema.fi or
           key_name == cls.Schema.MultiKeySchema.st):
            key_value = re.sub(r'[^a-zA-Z]', '', key_value)
            return key_value

        if(key_name == cls.Schema.MultiKeySchema.zip):
            key_value = re.split('-', key_value)[0]
            return key_value

        if(key_name == cls.Schema.MultiKeySchema.country):
            key_value = re.sub(r'[^a-zA-Z]', '', key_value)[:2]
            return key_value

    def add_users(self,
                  schema,
                  users,
                  is_raw=False,
                  app_ids=None,
                  pre_hashed=None,
                  session=None):
        """Adds users to this CustomAudience.

        Args:
            schema: A CustomAudience.Schema value specifying the type of values
                in the users list.
            users: A list of identities respecting the schema specified.

        Returns:
            The FacebookResponse object.
        """
        return self.get_api_assured().call(
            'POST',
            (self.get_id_assured(), 'users'),
            params=self.format_params(
                schema,
                users,
                is_raw,
                app_ids,
                pre_hashed,
                session,
            ),
        )

    def remove_users(self,
                     schema,
                     users,
                     is_raw=False,
                     app_ids=None,
                     pre_hashed=None,
                     session=None):
        """Deletes users from this CustomAudience.

        Args:
            schema: A CustomAudience.Schema value specifying the type of values
                in the users list.
            users: A list of identities respecting the schema specified.

        Returns:
            The FacebookResponse object.
        """
        return self.get_api_assured().call(
            'DELETE',
            (self.get_id_assured(), 'users'),
            params=self.format_params(
                schema,
                users,
                is_raw,
                app_ids,
                pre_hashed,
                session,
            ),
        )

    def share_audience(self, account_ids):
        """Shares this CustomAudience with the specified account_ids.

        Args:
            account_ids: A list of account ids.

        Returns:
            The FacebookResponse object.
        """
        return self.get_api_assured().call(
            'POST',
            (self.get_id_assured(), 'adaccounts'),
            params={'adaccounts': account_ids},
        )

    def unshare_audience(self, account_ids):
        """Unshares this CustomAudience with the specified account_ids.

        Args:
            account_ids: A list of account ids.

        Returns:
            The FacebookResponse object.
        """
        return self.get_api_assured().call(
            'DELETE',
            (self.get_id_assured(), 'adaccounts'),
            params={'adaccounts': account_ids},
        )