Server ke Server: Panduan Pengaturan Server Lelang

Panduan ini menjelaskan cara Anda dapat membangun server lelang internal. Dalam panduan langkah demi langkah di bawah ini, kami akan menggunakan contoh penawaran pada iklan interstisial. Pastikan Anda sudah mengetahui cara menggunakan iklan interstisial Audience Network. Penawaran juga mendukung format Native, Spanduk, Interstisial, Video In-Stream, dan Video Berhadiah. Anda dapat memeriksa format iklan yang didukung) di bawah ini untuk mengintegrasikan format iklan yang berbeda.

Langkah Pengaturan Server Lelang

Langkah 1: Menentukan platform pada server Anda

Langkah 2: Menghasilkan Permintaan ORTB dari server Anda

Langkah 3: Mengeksekusi Permintaan ORTB dari server Anda

Langkah 4: Menjalankan lelang pada server Anda

Langkah 5: Mengaktifkan notifikasi Menang/Kalah/Timeout

Langkah 6: Membawa pemenang kembali ke sisi klien Anda

Langkah Pengaturan Server Lelang

Langkah 1: Menentukan platform pada server Anda

Permintaan ORTB yang dikirim ke titik akhir penawaran Audience Network harus berisi informasi perangkat dan aplikasi. Berikut ini contoh muatan dalam permintaan ORTB:

{
// Device information from client side
'device': {
'ifa': '${DEVICE_ID}',
'dnt': '0',
'ip': '127.0.0.1'
},
// Application information
'app': {
'ver': '1.0',
'bundle': 'com.facebook.audiencenetwork.AdUnitsSample',
'publisher': {
// For server to server bidding integration, this is your application id on Facebook
'id': '${APP_ID}',
}
},
// Placement information we can store on server
'imp': [
{
'id': 'banner_test_bid_req_id',
// This is the placement id for Audience Network
'tagid': '${PLACEMENT_ID}',
'banner': {
'w': -1,
'h': 50,
},
},
],
// Optional regulations object from client side
'regs': {
'coppa': 0,
},
// In server to server integration, you can use the Facebook app id as platform id here
'ext': {
'platformid': '${PLATFORM_ID}',
// Mediation partner Platform ID or publisher FB app ID, mandatory.
'authentication_id': '${AUTHENTICATION_ID}',   
// Authentication token to validate the originator of the request.
'security_app_id': '${AN_SECURITY_APP_MY_SECURITY_APP_ID}',
// Security app id used to generate authentication_id.
's2s_version': '${VERSION_NUMBER}',
// Version of the integration. Max 16 characters.
},
// buyeruid is the user bidder token generated on client side, using the `getBidderToken` method from the Audience Network SDK. 
// It's constant through out app session so you could cache it on the client side
'user': {
'buyeruid': 'mybuyeruid',
},
// Test mode flag
'test': '1',
// Time out setting we can store on server
'tmax': 1000,
// Request ID we can generate on server
'id': 'banner_test_bid_req_id',
// Auction setting we can store on server
'at': 1,
}

Muatan permintaan ORTB di atas diperlukan oleh Audience Network. Namun, pada server lelang Anda sendiri, sebenarnya Anda dapat menentukan beberapa spesifikasi aplikasi, seperti ID aplikasi, ID penempatan, dan beberapa parameter lainnya dalam konfigurasi server; sehingga, aplikasi sisi klien Anda hanya perlu mengirim permintaan yang sederhana. Server Anda dapat mengulang informasi penempatan dan membangun permintaan ORTB akhir. Di bawah ini adalah sampel pengaturan server lelang:

{
"bidding_source_platforms": [
{
"platform_name": "audience_network",
"end_point": "https://an.facebook.com/${PLATFORM_ID}/placementbid.ortb",
"timeout": 1000,
"timeout_notification_url": "https://www.facebook.com/audiencenetwork/nurl/?partner=${PARTNER_FBID}&app=${APP_FBID}&auction=${AUCTION_ID}&ortb_loss_code=2"
}
],
"apps": [
{
"app_id": "101",
"app_name": "My example app",
"placements": [
{
"placement_id": "1",
"placement_name": "My example placement",
"ad_format": "interstitial",
"bidding_source_placement_ids":[
{
"platform_name": "audience_network",
"platform_app_id": "${APP_ID}",
"platform_placement_id": "${PLACEMENT_ID}"
}
]
}
]
}
]
}

Dengan pengaturan server lelang di atas, aplikasi sisi klien hanya perlu mengirim permintaan yang sederhana dengan "app_id":"101" dan "placement_id":"1" ke server Anda; sehingga, server Anda akan dapat mencari informasi penempatan yang lengkap, seperti placement_id, ad_format, platform_name, dll. Berikut ini adalah sampel permintaan muatan yang sederhana dari sisi klien Anda:

{
// App ID and placement ID are used to look up settings from
// server settings
'app_id': '101',
'placement_id': '1',

'bundle': 'com.facebook.samples.s2sbiddingclient',
'bundle_version': '1.0',

// Device specifics
'ifa': '${DEVICE_ID}',
'coppa': 0,
'dnt': 0,

// buyer_tokens are the user tokens required for different networks
'buyer_tokens': {
// Token for audience network from BidderTokenProvider.getBidderToken(context)
// This can be cached for the same app session
'audience_network': 'my-buyeruid',
},
}

Setelah permintaan yang sederhana dikirim ke server lelang, Anda akan dapat mencari informasi lengkap tentang penempatan, perangkat, dan aplikasi dengan app_id dan placement_id di pengaturan server lelang Anda. Berikut ini contoh hasil pencarian:

{
"placement_id": "1",
"placement_name": "My example placement",
"ad_format": "interstitial",
"bidding_source_placement_ids":[
{
"platform_name": "audience_network",
"platform_app_id": "${APP_ID}",
"platform_placement_id": "${PLACEMENT_ID}"
}
]
}

Langkah 2: Menghasilkan Permintaan ORTB dari server Anda

Setelah server lelang menerima permintaan lelang, server perlu membangun permintaan penawaran untuk setiap sumber permintaan. Inilah titik akhir di app.py untuk menerima permintaan lelang:

@app.route('/get_bid', methods=['POST'])
def get_bid():
'''
The actual endpoint that expects a ClientRequest in the parameters
'''
# Initialize the server settings
ServerSettings.initialize(
app.config['bidding_source_platforms'],
app.config['apps']
)

request_params = request.get_json(force=True)

# See the code sample below for this function in `bid_manager.py`
(code, response) = get_bid_response(
request.remote_addr,
request.user_agent.string,
request_params)

app.logger.debug('server response: {0} {1}'.format(code, response))
return Response(
json.dumps(response),
status=code,
mimetype='application/json'
)

Dalam bid_manager.py, permintaan lelang dari klien berisi app_id dan placement_id yang akan digunakan untuk mencari informasi penempatan lengkap dalam pengaturan server.

# Return Auction Result - Winner - back to client side
def get_bid_response(ip, user_agent, request_params):
"""Get the winner bid response for the current request"""
try:
app_id = request_params['app_id']
placement_id = request_params['placement_id']
auction_id = get_auction_id()
...
# Find placement in the settings
placement = ServerSettings.get_placement(app_id, placement_id)

# Collect bid requests for different platforms
bid_requests = get_bid_requests(
ip,
user_agent,
auction_id,
placement,
request_params)

except Exception as e:
raise ParameterError("Error in request parameters: {}".format(str(e)))
...
return final_response

# Get all bid requests for different platforms
def get_bid_requests(ip, user_agent, auction_id, placement, request_params):
"""Create bid requests based on the internal placement setting"""

...

(end_point, data, timeout_notification_url) = get_bid_request(
ip,
user_agent,
auction_id,
platform_name,
platform_app_id,
platform_placement_id,
ad_format,
request_params)

if data is not None:
results.append({
'platform_name': platform_name,
'end_point': end_point,
'data': data,
'timeout_notification_url': timeout_notification_url,
})

# current_app.logger.debug("requests: {}".format(results))
return results

# Get bid request for each platform
def get_bid_request(
ip,
user_agent,
auction_id,
platform_name,
platform_app_id,
platform_placement_id,
ad_format,
request_params
):
"""Create bid request for a specific platform"""
if platform_name == 'audience_network':

return audience_network.get_bid_request(
ip,
user_agent,
auction_id,
platform_app_id,
platform_placement_id,
ad_format,
request_params)

else:
return (None, None, None)

Kemudian, di audience_network.py, fungsi get_bid_request akan menghasilkan permintaan ORTB terakhir untuk Audience Network berdasarkan informasi penempatan lengkap.

def get_bid_request(
ip,
user_agent,
auction_id,
platform_app_id,
platform_placement_id,
ad_format,
request_params
):
'''
Gather the required bid request parameters for networks. The parameters
consist of platform settings like app id, placement ids, ad sizes etc., and
client side information such as device information, user agent etc. We use
the `settings.json` file to store platform specific settings, and the
client request to retrieve the clietn specific information.
'''
platform = ServerSettings.get_platform('audience_network')
end_point = platform['end_point']
timeout = platform['timeout']
timeout_notification_url = platform['timeout_notification_url']

timeout_notification_url.replace('${PARTNER_FBID}', platform_app_id)
timeout_notification_url.replace('${APP_FBID}', platform_app_id)
timeout_notification_url.replace('${AUCTION_ID}', auction_id)

imp = []
if ad_format == 'native':
imp.append({
'id': auction_id,
'native': {
'w': -1,
'h': -1,
},
'tagid': platform_placement_id,
})
elif ad_format == 'banner':
imp.append({
'id': auction_id,
'banner': {
'w': -1,
'h': 50,
},
'tagid': platform_placement_id,
})
elif ad_format == 'interstitial':
imp.append({
'id': auction_id,
'banner': {
'w': 0,
'h': 0,
},
'tagid': platform_placement_id,
'instl': 1,
})
elif ad_format == 'rewarded_video':
imp.append({
'id': auction_id,
'video': {
'w': 0,
'h': 0,
'linearity': 2,
},
'tagid': platform_placement_id,
})
elif ad_format == 'instream_video':
imp.append({
'id': auction_id,
'video': {
'w': 0,
'h': 0,
'linearity': 1,
},
'tagid': platform_placement_id,
})
else:
raise ParameterError("Incorrect ad format")

typed_ip = ipaddress.ip_address(ip)
device = {
'ifa': request_params['ifa'],
'ua': user_agent,
'dnt': request_params['dnt'],
}
if type(typed_ip) is ipaddress.IPv6Address:
device['ipv6'] = ip
else:
device['ip'] = ip

# Construct the ORTB request
request = {
'id': auction_id,
'imp': imp,
'app': {
'bundle': request_params['bundle'],
'ver': request_params['bundle_version'],
'publisher': {
'id': platform_app_id,
}
},
'device': device,
'regs': {
'coppa': request_params['coppa'],
},
'user': {
'buyeruid': request_params['buyer_tokens']['audience_network'],
},
'ext': {
'
': platform_app_id,
},
'at': 1,
'tmax': timeout,
'test': request_params['test'],
}

return (end_point, request, timeout_notification_url)

Langkah 3: Mengeksekusi Permintaan ORTB dari server Anda

Setelah objek permintaan ORTB dibuat di atas, kita dapat mengirimkan permintaan ke titik akhir Audience Network di https://an.facebook.com/${PLATFORM_ID}/placementbid.ortb menggunakan permintaan HTTP, dengan menggunakan post dan Content-Type: application/json.

Dalam bid_manager.py, setelah semua permintaan tawaran untuk setiap platform dikumpulkan, exec_bid_requests akan dipanggil untuk setiap platform:

# Return Auction Result - Winner - back to client side
def get_bid_response(ip, user_agent, request_params):
"""Get the winner bid response for the current request"""
...
# Execute bid requests by network
bid_responses = []
for bid_request in bid_requests:
(code, response) = exec_bid_request(
bid_request['platform_name'],
bid_request['end_point'],
bid_request['data'],
bid_request['timeout_notification_url'])

bid_responses.append({
'platform_name': bid_request['platform_name'],
'code': code,
'response': response,
})

final_response = run_auction(bid_responses, placement)
return final_response

# Execute bid request for different platform (network)
def exec_bid_request(
platform_name,
end_point,
request_params,
timeout_notification_url
):
'''
Actually run the bid requests for the networks.
'''
if platform_name == 'audience_network':
return audience_network.exec_bid_request(
end_point,
request_params,
timeout_notification_url,
)
else:
raise InternalError("Invalid platform: {}".format(platform_name))

Header HTTP berikut (baik penawaran dan tanpa penawaran) dalam tanggapan akan diatur serta berisi informasi yang berguna untuk pemecahan masalah dan harus dicatat di server lelang:

• X-FB-AN-Request-ID: ID Permintaan diperlukan oleh Audience Network untuk mengunduh permintaan tertentu. Silakan catat setiap kali meminta dukungan.
• X-FB-AN-Errors: Daftar kesalahan yang ditemui, berguna untuk memahami alasan tidak ada tawaran.
• X-FB-Debug: Beberapa informasi tentang permintaan ini yang dapat Anda kirimkan ke perwakilan akun Anda di Audience Network untuk memecahkan masalah.

Catatan: untuk meminimalkan latensi, Anda harus menambahkan X-FB-Pool-Routing-Token ke permintaan penawaran Anda.

• X-FB-Pool-Routing-Token: Token ini digunakan untuk merutekan permintaan ke pusat data terdekat kami, dan nilainya sama dengan user.buyeruid.

Dalam audience_network.py, permintaan ORTB akan dikirim ke Audience Network, dan tanggapan penawaran akan dikirimkan ke server lelang:

def exec_bid_request(
end_point,
request_params,
timeout_notification_url
):
try:
platform = ServerSettings.get_platform('audience_network')
headers = {
'Content-Type': 'application/json; charset=utf-8',
'X-FB-Pool-Routing-Token': request_params['user']['buyeruid'],
}
timeout = platform['timeout']
r = requests.post(
end_point,
json=request_params,
headers=headers,
# Timeout in settings.json in ms
timeout=(timeout / 1000),
)
except Exception as e:
current_app.logger.error(BID_TIMEOUT)

# Send time out notification
r = requests.get(timeout_notification_url, timeout)
return (500, BID_TIMEOUT)

if r.status_code == requests.codes.ok:
try:
data = json.loads(r.text)
current_app.logger.debug('Audience Network response: {}'.format(
data
))
# Parse response from Audience Network with the ORTBResponse
ortb_response = ORTBResponse(data)
except Exception as e:
current_app.logger.error(
PARSE_ERROR + "{}".format(e)
)
return (500, PARSE_ERROR + "{}".format(e))

return (r.status_code, ortb_response)

else:
# The error message is stored in the X-FB-AN-Errors header
error_header = r.headers.get('x-fb-an-errors')
debug_header = r.headers.get('x-fb-debug')
bid_request_id = r.headers.get('x-fb-an-request-id')

if r.status_code == 400:
error_message = INVALID_BID + error_header + INVALID_BID_ADVICE
elif r.status_code == 204:
error_message = NO_BID + error_header
else:
error_message = UNEXPECTED_ERROR

# Log error information for debugging
error = {
'bid_request_id': bid_request_id,
'debug_header': debug_header,
'error_message': error_message,
}
current_app.logger.error(error)

# Respond error status code to client
return (r.status_code, error_message)

Anda dapat mengirimkan isi permintaan yang dikompresi dalam bentuk gzip biner jika Anda memberikan header Content-Encoding:gzip ke permintaan.

Langkah 4: Menjalankan lelang di server Anda

Sekarang kita sudah memiliki tanggapan penawaran dari berbagai platform (jaringan). Dalam bid_manager.py, ungsi get_bid_response akan bertanggung jawab untuk membandingkan tanggapan penawaran yang terisi dan memutuskan penawaran tertinggi - Pemenang.

def get_bid_response(ip, user_agent, request_params):
"""Get the winner bid response for the current request"""
...
final_response = run_auction(bid_responses, placement)
return final_response

def run_auction(bid_responses, placement):
"""Run auction based on raw responses and create the response object"""
other_bid = 1
response = (204, None)  # default is 204 no fill

for bid_response in bid_responses:
if bid_response['platform_name'] == 'audience_network':
if bid_response['code'] == 200:
ortb_response = bid_response['response']
if ortb_response.price > other_bid:
response = create_response(bid_response, placement)
current_app.logger.debug(
'Audience Network bid: {} won!'.format(
ortb_response.price
)
)
notify_result(bid_response)
else:
current_app.logger.debug(
'Audience Network bid: {} lost!'.format(
ortb_response.price
)
)
notify_result(bid_response, 102)
else:
current_app.logger.debug(bid_response['response'])

return response

Karena Audience Network adalah satu-satunya penawar dalam contoh kami, metode lelang yang berjalan hanya membandingkan tawaran yang dikembalikan dengan beberapa nilai harga dan memutuskan apakah tawaran itu memenangkan lelang. Akibatnya, jika tawaran yang dikembalikan dari Audience Network lebih tinggi dari 1 dolar, kami menganggap Audience Network telah memenangkan tawaran. Jika tidak, kami memperlakukannya sebagai pihak yang kalah lelang.

Langkah 5: Mengaktifkan notifikasi Menang/Kalah/Tagihan/Timeout

"https://www.facebook.com/audiencenetwork/nurl/?partner=${PARTNER_FBID}&app=${APP_FBID}&placement=${PLACEMENT_FBID}&auction=${AUCTION_ID}&impression=${IMPRESSION_ID}&request=${BID_REQUEST_ID}&bid=${BID_ID}&ortb_loss_code=0&clearing_price=${AUCTION_PRICE}"

"https://www.facebook.com/audiencenetwork/nurl/?partner=${PARTNER_FBID}&app=${APP_FBID}&placement=${PLACEMENT_FBID}&auction=${AUCTION_ID}&impression=${IMPRESSION_ID}&request=${BID_REQUEST_ID}&bid=${BID_ID}&ortb_loss_code=${AUCTION_LOSS}&clearing_price=${AUCTION_PRICE}"

"https://www.facebook.com/audiencenetwork/burl/?partner=${PARTNER_FBID}&app=${APP_FBID}&placement=${PLACEMENT_FBID}&auction=${AUCTION_ID}&impression=${IMPRESSION_ID}&request=${BID_REQUEST_ID}&bid=${BID_ID}&ortb_loss_code=0&clearing_price=${AUCTION_PRICE}"

"https://www.facebook.com/audiencenetwork/nurl/?partner=${PARTNER_FBID}&app=${APP_FBID}&auction=${AUCTION_ID}&ortb_loss_code=2"

Langkah 6: Membawa pemenang kembali ke sisi klien Anda

Setelah menjalankan lelang, kita membuat objek tanggapan dan mengembalikannya ke aplikasi klien. Berikut adalah metode dalam contoh di bid_manager.py yang membuat tanggapan akhir dari server lelang:

def create_response(bid_response, placement):
"""Create response object based on the auction result"""
ad_format = placement['ad_format']
platform_name = bid_response['platform_name']
platform_placement_id = None

for bidding_source_placement_id in placement[
'bidding_source_placement_ids'
]:
if bidding_source_placement_id['platform_name'] == platform_name:
platform_placement_id = bidding_source_placement_id[
'platform_placement_id'
]

if platform_placement_id is None:
raise InternalError("Platform placement ID not found!")

bid_payload = None
if platform_name == 'audience_network':
bid_payload = bid_response['response'].adm
else:
raise InternalError("Invalid platform")

return (200, {
'placement_id': placement['placement_id'],
'ad_format': ad_format,
'platform_name': platform_name,
'platform_placement_id': platform_placement_id,
'bid_payload': bid_payload,
})

Akhirnya, contoh server kami dapat membuat tanggapan kepada klien ini untuk memberi tahu platform mana yang akan digunakan:

{
'placement_id': string, // Placement identifier for the auction server
'ad_format': string, // Format of the placement
'platform_name': string, // Which platform won the auction, for example 'audience_network'
'platform_placement_id': string, // Placement ID for the platform, for example the placement ID for Audience network
'bid_payload': string, // The JSON string payload for the platform SDK to load the final ad
}

Berikutnya: Integrasi Langkah demi Langkah Klien

• Langkah-Langkah Pengaturan Sisi Klien Android
• Langkah-Langkah Pengaturan Sisi Klien iOS
• Pengujian
• Pemecahan Masalah