คู่มือนี้มีวิธีอัปโหลด Conversion ออฟไลน์โดยละเอียดโดยใช้บริการ API ของ Campaign Manager 360 Conversions
ก่อนที่จะดําเนินการต่อ เราขอแนะนําให้คุณอ่านภาพรวมสําหรับข้อมูลเบื้องต้นเกี่ยวกับ Conversion ออฟไลน์ และทําความคุ้นเคยกับแนวคิดที่ได้เพิกเฉยในคู่มือนี้
กําหนดค่าทรัพยากร Conversion
ขั้นตอนแรกในกระบวนการอัปโหลด Conversion คือการสร้างออบเจ็กต์ทรัพยากร Conversion
อย่างน้อย 1 รายการ ออบเจ็กต์แต่ละรายการเหล่านี้แทนเหตุการณ์ Conversion เดียว และมีช่องที่ต้องกรอกอยู่ 2-3 ช่อง
ช่อง | คำอธิบาย |
---|---|
floodlightActivityId |
กิจกรรม Floodlight ที่เชื่อมโยงกับ Conversion นี้ |
floodlightConfigurationId |
การกําหนดค่า Floodlight ที่ใช้โดยกิจกรรมที่ระบุ |
ordinal |
ค่าที่ใช้ในการควบคุมวิธีแปลง Conversion จากอุปกรณ์หรือผู้ใช้เดียวกันในวันเดียวกัน ดูคําถามที่พบบ่อยสําหรับข้อมูลเพิ่มเติม |
timestampMicros |
การประทับเวลาของ Conversion ในหน่วยไมโครวินาทีนับตั้งแต่เริ่มต้น Unix Epoch |
นอกจากนี้ แต่ละออบเจ็กต์ต้องมีช่องต่อไปนี้ 1 ช่อง
ช่อง | คำอธิบาย |
---|---|
encryptedUserId |
รหัสผู้ใช้ที่เข้ารหัสเพียงครั้งเดียวซึ่งได้รับมาจากมาโครที่ตรงกัน%m หรือการโอนข้อมูล |
encryptedUserIdCandidates[] |
รายการรหัสผู้ใช้ที่เข้ารหัสมาจากมาโครที่ตรงกัน%m หรือการโอนข้อมูล ระบบจะใช้รหัสแรกที่มีการเปิดบันทึก Floodlight ก่อน timestampMicros ที่ระบุไว้ หากไม่มีรหัสใดที่ตรงกันกับการรับแสงที่มีอยู่ ระบบจะแสดงข้อผิดพลาด |
dclid |
หมายเลขระบุคลิกดิสเพลย์ที่สร้างโดย Campaign Manager 360 หรือ Display & Video 360 |
gclid |
หมายเลขระบุคลิกของ Google ที่สร้างโดย Google Ads หรือ Search Ads 360 |
matchId |
ตัวระบุที่ไม่ซ้ํากันของผู้ลงโฆษณาที่สร้างไว้ซึ่งส่งผ่านไปยัง Campaign Manager 360 ผ่านแท็ก Floodlight |
mobileDeviceId |
รหัสอุปกรณ์เคลื่อนที่ที่ไม่ได้เข้ารหัสในรูปแบบ IDFA หรือ AdID หรือตัวระบุทีวีที่เชื่อมต่ออินเทอร์เน็ตสําหรับการโฆษณา (IFA) จากแพลตฟอร์มอุปกรณ์ CTV ที่รองรับ (Roku, Fire TV, Android TV, Apple TV, Xbox, Samsung, Vizio) โปรดทราบว่า Google ไม่สนับสนุน IFA บนทีวีที่เชื่อมต่ออินเทอร์เน็ต |
ดูช่องที่ไม่บังคับได้ในเอกสารอ้างอิง โปรดทราบว่าแม้จะมีจํานวนอย่างน้อย 1 ช่อง แต่ต้องมีจํานวนอย่างน้อย 1 ช่องเพื่อให้ Conversion นับรวมในเมตริกบางรายการ (เช่น Conversion ทั้งหมด) ขณะเรียกใช้รายงาน
ตัวอย่างด้านล่างแสดงการสร้างออบเจ็กต์ทรัพยากร Conversion แบบง่าย
C#
// Generate a timestamp in milliseconds since Unix epoch. TimeSpan timeSpan = DateTime.UtcNow - new DateTime(1970, 1, 1); long currentTimeInMilliseconds = (long) timeSpan.TotalMilliseconds; // Find the Floodlight configuration ID based on the provided activity ID. FloodlightActivity floodlightActivity = service.FloodlightActivities.Get(profileId, floodlightActivityId).Execute(); long floodlightConfigurationId = (long) floodlightActivity.FloodlightConfigurationId; // Create the conversion. Conversion conversion = new Conversion(); conversion.EncryptedUserId = conversionUserId; conversion.FloodlightActivityId = floodlightActivityId; conversion.FloodlightConfigurationId = floodlightConfigurationId; conversion.Ordinal = currentTimeInMilliseconds.ToString(); conversion.TimestampMicros = currentTimeInMilliseconds * 1000;
Java
long currentTimeInMilliseconds = System.currentTimeMillis(); // Find Floodlight configuration ID based on the provided activity ID. FloodlightActivity floodlightActivity = reporting.floodlightActivities() .get(profileId, floodlightActivityId).execute(); long floodlightConfigurationId = floodlightActivity.getFloodlightConfigurationId(); Conversion conversion = new Conversion(); conversion.setEncryptedUserId(encryptedUserId); conversion.setFloodlightActivityId(floodlightActivityId); conversion.setFloodlightConfigurationId(floodlightConfigurationId); conversion.setOrdinal(String.valueOf(currentTimeInMilliseconds)); conversion.setTimestampMicros(currentTimeInMilliseconds * 1000);
PHP
$currentTimeInMicros = time() * 1000 * 1000; // Find Floodlight configuration ID based on provided activity ID. $activity = $this->service->floodlightActivities->get( $values['user_profile_id'], $values['floodlight_activity_id'] ); $floodlightConfigId = $activity->getFloodlightConfigurationId(); $conversion = new Google_Service_Dfareporting_Conversion(); $conversion->setEncryptedUserId($values['encrypted_user_id']); $conversion->setFloodlightActivityId($values['floodlight_activity_id']); $conversion->setFloodlightConfigurationId($floodlightConfigId); $conversion->setOrdinal($currentTimeInMicros); $conversion->setTimestampMicros($currentTimeInMicros);
Python
# Look up the Floodlight configuration ID based on activity ID. floodlight_activity = service.floodlightActivities().get( profileId=profile_id, id=floodlight_activity_id).execute() floodlight_config_id = floodlight_activity['floodlightConfigurationId'] current_time_in_micros = int(time.time() * 1000000) # Construct the conversion. conversion = { 'encryptedUserId': encrypted_user_id, 'floodlightActivityId': floodlight_activity_id, 'floodlightConfigurationId': floodlight_config_id, 'ordinal': current_time_in_micros, 'timestampMicros': current_time_in_micros }
Ruby
# Look up the Floodlight configuration ID based on activity ID. floodlight_activity = service.get_floodlight_activity(profile_id, floodlight_activity_id) floodlight_config_id = floodlight_activity.floodlight_configuration_id current_time_in_micros = DateTime.now.strftime('%Q').to_i * 1000 # Construct the conversion. conversion = DfareportingUtils::API_NAMESPACE::Conversion.new( encrypted_user_id: encrypted_user_id, floodlight_activity_id: floodlight_activity_id, floodlight_configuration_id: floodlight_config_id, ordinal: current_time_in_micros, timestamp_micros: current_time_in_micros )
ระบุข้อมูลการเข้ารหัส
หากคุณวางแผนที่จะระบุแหล่งที่มาของ Conversion ออฟไลน์เป็นรหัสผู้ใช้ที่เข้ารหัสไว้ อย่างเช่นในตัวอย่างก่อนหน้า คุณจะต้องระบุรายละเอียดเกี่ยวกับวิธีเข้ารหัส Conversion เหล่านั้นเป็นส่วนหนึ่งของคําขอการแทรก โดยเฉพาะอย่างยิ่ง คุณจะต้องทราบข้อมูลต่อไปนี้
แหล่งที่มาของการเข้ารหัสซึ่งอธิบายว่ากลุ่มรหัสที่เข้ารหัสมาจากที่ใด ค่าที่ยอมรับได้คือ
AD_SERVING
สําหรับรหัสที่มาจากมาโครการจับคู่ %m หรือDATA_TRANSFER
สําหรับรหัสที่มาจากไฟล์การโอนข้อมูลเอนทิตีการเข้ารหัสซึ่งเป็นชุดค่าที่ไม่ซ้ํากันที่ใช้เข้ารหัสรหัสผู้ใช้ โดยทั่วไปค่าเหล่านี้จะเกี่ยวข้องกับบัญชี Campaign Manager 360 เมื่อต้นทางเป็นการโอนข้อมูล หรือผู้ลงโฆษณา Campaign Manager 360 เมื่อแหล่งที่มาเป็นมาโคร %m แต่ก็ไม่เป็นเช่นนั้นเสมอไป หากไม่แน่ใจ โปรดติดต่อตัวแทนฝ่ายดูแลลูกค้าของ Campaign Manager 360 หรือทีมสนับสนุนของ Campaign Manager 360
หากจําเป็น ให้สร้างออบเจ็กต์ EncryptionInfo
ที่ระบุค่าเหล่านี้เป็นขั้นตอนที่ 2 ของกระบวนการอัปโหลด Conversion
C#
// Create the encryption info. EncryptionInfo encryptionInfo = new EncryptionInfo(); encryptionInfo.EncryptionEntityId = encryptionEntityId; encryptionInfo.EncryptionEntityType = encryptionEntityType; encryptionInfo.EncryptionSource = encryptionSource;
Java
// Create the encryption info. EncryptionInfo encryptionInfo = new EncryptionInfo(); encryptionInfo.setEncryptionEntityId(encryptionEntityId); encryptionInfo.setEncryptionEntityType(encryptionEntityType); encryptionInfo.setEncryptionSource(encryptionSource);
PHP
$encryptionInfo = new Google_Service_Dfareporting_EncryptionInfo(); $encryptionInfo->setEncryptionEntityId($values['encryption_entity_id']); $encryptionInfo->setEncryptionEntityType($values['encryption_entity_type']); $encryptionInfo->setEncryptionSource($values['encryption_source']);
Python
# Construct the encryption info. encryption_info = { 'encryptionEntityId': encryption_entity_id, 'encryptionEntityType': encryption_entity_type, 'encryptionSource': encryption_source }
Ruby
# Construct the encryption info. encryption_info = DfareportingUtils::API_NAMESPACE::EncryptionInfo.new( encryption_entity_id: encryption[:entity_id], encryption_entity_type: encryption[:entity_type], encryption_source: encryption[:source] )
โปรดทราบว่าคําขอแทรกแต่ละรายการอาจมีออบเจ็กต์ EncryptionInfo
ได้เพียง 1 รายการเท่านั้น ซึ่งหมายความว่า Conversion ทั้งหมดที่รวมอยู่ในคําขอหนึ่งๆ ต้องมาจากแหล่งที่มาเดียวกันและใช้เอนทิตีการเข้ารหัสเดียวกัน
สร้างคําขอแทรก
ขั้นตอนสุดท้ายในกระบวนการนี้คือการอัปโหลด Conversion ด้วยการโทรหา batchinsert
วิธีนี้ยอมรับออบเจ็กต์ ConversionsBatchInsertRequest
ซึ่งจะรวมชุด Conversion ที่จะอัปโหลดเข้ากับข้อมูลการเข้ารหัสที่เกี่ยวข้อง (เมื่อจําเป็น)
C#
// Insert the conversion. ConversionsBatchInsertRequest request = new ConversionsBatchInsertRequest(); request.Conversions = new List<Conversion>() { conversion }; request.EncryptionInfo = encryptionInfo; ConversionsBatchInsertResponse response = service.Conversions.Batchinsert(request, profileId).Execute();
Java
ConversionsBatchInsertRequest request = new ConversionsBatchInsertRequest(); request.setConversions(ImmutableList.of(conversion)); request.setEncryptionInfo(encryptionInfo); ConversionsBatchInsertResponse response = reporting.conversions() .batchinsert(profileId, request).execute();
PHP
$batch = new Google_Service_Dfareporting_ConversionsBatchInsertRequest(); $batch->setConversions([$conversion]); $batch->setEncryptionInfo($encryptionInfo); $result = $this->service->conversions->batchinsert( $values['user_profile_id'], $batch );
Python
# Insert the conversion. request_body = { 'conversions': [conversion], 'encryptionInfo': encryption_info } request = service.conversions().batchinsert(profileId=profile_id, body=request_body) response = request.execute()
Ruby
# Construct the batch insert request. batch_insert_request = DfareportingUtils::API_NAMESPACE::ConversionsBatchInsertRequest.new( conversions: [conversion], encryption_info: encryption_info ) # Insert the conversion. result = service.batchinsert_conversion(profile_id, batch_insert_request)
โปรดทราบว่า Campaign Manager 360 จะพยายามแทรกแต่ละ Conversion ในคําขออย่างเต็มความสามารถ แทนที่จะแทรกทั้งกลุ่มเป็นธุรกรรมทั้งหมดและไม่ต้องดําเนินการใดๆ หากแทรก Conversion บางรายการเป็นแบทช์
ก็อาจแทรกรายการอื่นไม่ครบ ดังนั้น เราขอแนะนําให้คุณตรวจสอบ ConversionsBatchInsertResponse
ที่ส่งคืนแล้วเพื่อดูสถานะของ Conversion แต่ละรายการ ดังนี้
C#
// Handle the batchinsert response. if (!response.HasFailures.Value) { Console.WriteLine("Successfully inserted conversion for encrypted user ID {0}.", conversionUserId); } else { Console.WriteLine("Error(s) inserting conversion for encrypted user ID {0}:", conversionUserId); ConversionStatus status = response.Status[0]; foreach(ConversionError error in status.Errors) { Console.WriteLine("\t[{0}]: {1}", error.Code, error.Message); } }
Java
if (!response.getHasFailures()) { System.out.printf("Successfully inserted conversion for encrypted user ID %s.%n", encryptedUserId); } else { System.out.printf("Error(s) inserting conversion for encrypted user ID %s:%n", encryptedUserId); // Retrieve the conversion status and report any errors found. If multiple conversions // were included in the original request, the response would contain a status for each. ConversionStatus status = response.getStatus().get(0); for (ConversionError error : status.getErrors()) { System.out.printf("\t[%s]: %s.%n", error.getCode(), error.getMessage()); } }
PHP
if (!$result->getHasFailures()) { printf( 'Successfully inserted conversion for encrypted user ID %s.', $values['encrypted_user_id'] ); } else { printf( 'Error(s) inserting conversion for encrypted user ID %s:<br><br>', $values['encrypted_user_id'] ); $status = $result->getStatus()[0]; foreach ($status->getErrors() as $error) { printf('[%s] %s<br>', $error->getCode(), $error->getMessage()); } }
Python
if not response['hasFailures']: print ('Successfully inserted conversion for encrypted user ID %s.' % encrypted_user_id) else: print ('Error(s) inserting conversion for encrypted user ID %s.' % encrypted_user_id) status = response['status'][0] for error in status['errors']: print '\t[%s]: %s' % (error['code'], error['message'])
Ruby
if result.has_failures puts format('Error(s) inserting conversion for encrypted user ID %s.', encrypted_user_id) status = result.status[0] status.errors.each do |error| puts format("\t[%s]: %s", error.code, error.message) end else puts format('Successfully inserted conversion for encrypted user ID %s.', encrypted_user_id) end
ช่อง status
ของการตอบกลับดังที่แสดงด้านบนจะมีออบเจ็กต์ ConversionStatus
ของทุก Conversion ที่รวมอยู่ในคําขอเดิม หากคุณสนใจเฉพาะ Conversion ที่แทรกไม่สําเร็จ ให้ใช้ช่อง hasFailures
เพื่อระบุได้อย่างรวดเร็วว่า
Conversion ใดก็ตามในกลุ่มที่ให้ไว้ล้มเหลว
ยืนยันว่าได้ประมวลผล Conversion แล้ว
โดยทั่วไป Conversion ที่อัปโหลดจะได้รับการประมวลผลและพร้อมรายงานได้ภายใน 24 ชั่วโมง หากต้องการยืนยันว่า Conversion ที่คุณอัปโหลดได้รับการประมวลผลแล้วหรือไม่ เราขอแนะนําให้เรียกใช้รายงานการแสดงผล Floodlight ซึ่งแตกต่างจากรายงานการระบุแหล่งที่มาอื่นๆ ตรงที่จะแสดงผลทั้งการระบุแหล่งที่มา (ที่เชื่อมโยงกับโฆษณา) และ Conversion ที่ไม่ได้ระบุแหล่งที่มาโดยค่าเริ่มต้น ซึ่งช่วยให้สามารถตรวจสอบได้อย่างรวดเร็วว่า Conversion ที่คุณส่งเข้ามาอยู่ใน Campaign Manager 360 แล้วหรือยัง