อัปโหลด Conversion

คู่มือนี้จะแสดงวิธีการโดยละเอียดในการอัปโหลด Conversion ออฟไลน์โดยใช้บริการ Campaign Manager 360 API Conversions ก่อนดำเนินการต่อ เราขอแนะนำให้อ่านภาพรวมเพื่อดูข้อมูลเบื้องต้นเกี่ยวกับ Conversion ออฟไลน์ และเพื่อทําความคุ้นเคยกับแนวคิดที่กล่าวถึงในคู่มือนี้

หมายเหตุ: แม้ว่า API จะรองรับ Conversion ออฟไลน์สําหรับ Campaign Manager 360 และ Display & Video 360 แต่ข้อมูลรถเข็นไม่พร้อมใช้งานสําหรับผลิตภัณฑ์ดังกล่าว ดูข้อมูลเพิ่มเติมเกี่ยวกับข้อมูลรถเข็นช็อปปิ้ง

กำหนดค่าทรัพยากร 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	ตัวระบุคลิก Display ที่ 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 ของ YouTube สำหรับทีวีที่เชื่อมต่ออินเทอร์เน็ต

ช่องที่ไม่บังคับจะระบุไว้ในเอกสารอ้างอิง โปรดทราบว่าฟิลด์จํานวนสินค้า (ไม่บังคับ) ต้องมีค่าอย่างน้อย 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 ที่มี encryptedUserId หรือ encryptedUserIdCandidates[]

หากวางแผนที่จะระบุแหล่งที่มาของ Conversion ออฟไลน์เป็นรหัสผู้ใช้ที่เข้ารหัส ดังตัวอย่างก่อนหน้านี้ คุณจะต้องระบุรายละเอียดบางอย่างเกี่ยวกับวิธีเข้ารหัสรหัสผู้ใช้ดังกล่าวเป็นส่วนหนึ่งของคําขอแทรก โดยเฉพาะอย่างยิ่ง คุณจะต้องทราบข้อมูลต่อไปนี้

1. แหล่งที่มาของการเข้ารหัส ซึ่งอธิบายว่ารหัสที่เข้ารหัสกลุ่มหนึ่งมาจากที่ใด ค่าที่ยอมรับได้คือ AD_SERVING สำหรับรหัสที่มาจากมาโครการจับคู่ %m หรือ DATA_TRANSFER สำหรับรหัสที่มาจากไฟล์การโอนข้อมูล

2. เอนทิตีการเข้ารหัส ซึ่งเป็นชุดค่าที่ไม่ซ้ำกันซึ่งใช้เข้ารหัสรหัสผู้ใช้ โดยปกติแล้ว ค่าเหล่านี้จะเกี่ยวข้องกับบัญชี 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 ได้เพียงรายการเดียว ซึ่งหมายความว่า 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 บางรายการในชุดไม่สําเร็จ ระบบอาจยังแทรก 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 ที่ไม่มีแหล่งที่มาโดยค่าเริ่มต้น วิธีนี้เหมาะสําหรับการตรวจสอบอย่างรวดเร็วว่า Conversion ที่ส่งไปยัง Campaign Manager 360 แล้วหรือยัง

หมายเหตุ: คุณควรทำการทดสอบการยืนยันโดยใช้ Conversion ล่าสุด รายงานการแสดงผล Floodlight จะไม่แสดง Conversion ที่ส่งมานานกว่า 28 วันหลังจากการประทับเวลา