Leads::subscribeToLeads() - Code Metrics - promopult/tiktok-marketing-api - Measure and Improve Code Quality continuously with Scrutinizer

Leads::subscribeToLeads() A
last analyzed 2025-02-17 19:03 UTC

↳ Parent: Leads

Complexity

Conditions	1
Paths	1

Size

Total Lines	16
Code Lines	8

Duplication

Lines	0
Ratio	0 %

Importance

Changes	1
Bugs	0	Features	0

Metric	Value
eloc	8
c	1
b	0
f	0
dl	0
loc	16
rs	10
cc	1
nc	1
nop	5

<?php

declare(strict_types=1);

namespace Promopult\TikTokMarketingApi\Service;

use Throwable;
use function json_decode;

/**
 * @psalm-suppress UnusedClass
 */
final class Leads extends \Promopult\TikTokMarketingApi\AbstractService
{
    /**
     * Create test lead
     *
     * After the subscription, you can use the endpoints below to perform an end-to-end testing for leads generation,
     * and clear the testing lead.
     *
     * @param ?int $advertiserId    If the instant form and the generated leads are under an ad account, you must
     *                              specify the advertiser ID.
     * @param ?int $libraryId       If the instant form and the generated leads are under a Business Center, you must
     *                              specify the ID of the form library that contains the instant form and leads.
     * @param int $pageId           The ID of the instant form.
     * @return array
     *
     * @throws Throwable
     * @see https://ads.tiktok.com/marketing_api/docs?id=1701890943400962
     */
    public function createTestLead(
        ?int $advertiserId,
        ?int $libraryId,
        int $pageId
    ): array {
        return $this->requestApi(
            'POST',
            '/open_api/v1.3/page/lead/mock/create/',
            [
                'advertiser_id' => $advertiserId,
                'library_id' => $libraryId,
                'page_id' => $pageId
            ]
        );
    }

    /**
     * Get test leads
     *
     * You can use this endpoint to get a test lead.
     *
     * @param ?int $advertiserId    If the instant form and the generated leads are under an ad account, you must
     *                              specify the advertiser ID.
     * @param ?int $libraryId       If the instant form and the generated leads are under a Business Center, you must
     *                              specify the ID of the form library that contains the instant form and leads.
     * @param int $pageId           The ID of the instant form.
     *
     * @return array
     *
     * @throws Throwable
     * @see https://ads.tiktok.com/marketing_api/docs?id=1709486980307969
     */
    public function getTestLeads(
        ?int $advertiserId,
        ?int $libraryId,
        int $pageId
    ): array {
        return $this->requestApi(
            'GET',
            '/open_api/v1.3/page/lead/mock/get/',
            [
                'advertiser_id' => $advertiserId,
                'library_id' => $libraryId,
                'page_id' => $pageId
            ]
        );
    }

    /**
     * Delete a test lead
     *
     * You can use this endpoint to delete an existing test lead.
     *
     * @param int $advertiserId
     * @param int $leadId
     * @return array
     *
     * @throws Throwable
     *
     * @see https://ads.tiktok.com/marketing_api/docs?id=1709487026425858
     */
    public function deleteTestLead(
        int $advertiserId,
        int $leadId
    ): array {
        return $this->requestApi(
            'POST',
            '/open_api/v1.3/page/lead/mock/delete/',
            [
                'advertiser_id' => $advertiserId,
                'lead_id' => $leadId
            ]
        );
    }

    /**
     * Create lead download task
     *
     * @param int $advertiserId
     * @param int|null $adId
     * @param int|null $pageId
     * @return array
     *
     * @throws Throwable
     *
     * @see https://ads.tiktok.com/marketing_api/docs?id=1701890942344193
     */
    public function createLeadDownloadTask(
        int $advertiserId,
        ?int $adId = null,
        ?int $pageId = null
    ): array {
        return $this->requestApi(
            'GET',
            '/open_api/v1.3/page/lead/task/',
            [
                'advertiser_id' => $advertiserId,
                'ad_id' => $adId,
                'page_id' => $pageId,
            ]
        );
    }

    /**
     * Get lead download task for status check
     *
     * Please note that the leads file will expire in 10 minutes after it was generated. You will get a file not exist
     * error if the file has expired.
     *
     * @param int $advertiserId
     * @param int $taskId
     * @return array
     *
     * @throws Throwable
     *
     * @see https://ads.tiktok.com/marketing_api/docs?id=1701890942344193
     */
    public function getLeadDownloadTask(
        int $advertiserId,
        int $taskId
    ): array {
        return $this->requestApi(
            'GET',
            '/open_api/v1.3/page/lead/task/',
            [
                'advertiser_id' => $advertiserId,
                'task_id' => $taskId
            ]
        );
    }

    /**
     * Download leads
     *
     * @param int $advertiserId
     * @param int $taskId
     *
     * @return string
     *
     * @throws Throwable
     *
     * @see https://ads.tiktok.com/marketing_api/docs?id=1709486183758850
     */
    public function downloadLeads(
        int $advertiserId,
        int $taskId
    ): string {
        $url = $this->credentials->getApiBaseUrl()
            . '/open_api/v1.3/page/lead/task/download/'
            . '?' . $this->prepareGetParams([
                'advertiser_id' => $advertiserId,
                'task_id' => $taskId
            ]);

        $headers = [
            'Access-Token' => $this->credentials->getAccessToken(),
        ];

        $request = new \GuzzleHttp\Psr7\Request(
            'GET',
            $url,
            $headers,
            null
        );

        $response = $this->sendRequest($request);

        /** @var array $decodedJson */
        $decodedJson = json_decode(
            (string) $response->getBody(),
            true
        );

        if (
            isset($decodedJson['code'])
            && $decodedJson['code'] != 0
        ) {
            throw new \Promopult\TikTokMarketingApi\Exception\ErrorResponse(
                (int) $decodedJson['code'],
                (string) $decodedJson['message'],
                $request,
                $response
            );
        }

        return (string) $response->getBody();
    }

    /**
     * Subscribe to leads
     *
     * You can subscribe to a page (instant form) to get leads generated from the page. If you do not want to receive
     * leads from a page any more, you can cancel the subscription.
     *
     * You can also get all subscriptions for an advertiser.
     *
     * You can subscribe to leads that are generated from a lead ad (instant form). Subscriptions are organized based on
     * Subcription IDs (subscription_id), not page IDs (page_id). Subscriptions are independent. A page can be included
     * in multiple subscriptions. Subscription status changes of a page in one subscription do not affect the
     * subscription status of this page in another subscription.
     *
     * @param int $appId
     * @param string $secret
     * @param array $subscriptionDetail
     * @param string $url
     * @param string $object
     * @return array
     *
     * @throws Throwable
     *
     * @see https://ads.tiktok.com/marketing_api/docs?id=1701890942854146
     */
    public function subscribeToLeads(
        int $appId,
        string $secret,
        array $subscriptionDetail,
        string $url,
        string $object = 'LEAD'
    ): array {
        return $this->requestApi(
            'POST',
            '/open_api/v1.3/subscription/subscribe/',
            [
                'app_id' => $appId,
                'secret' => $secret,
                'subscription_detail' => $subscriptionDetail,
                'object' => $object,
                'url' => $url
            ]
        );
    }

    /**
     * Cancel subscription
     *
     * @param int $appId
     * @param string $secret
     * @param int $subscriptionId
     * @return array
     *
     * @throws Throwable
     *
     * @see https://ads.tiktok.com/marketing_api/docs?id=1709486460752897
     */
    public function cancelSubscription(
        int $appId,
        string $secret,
        int $subscriptionId
    ): array {
        return $this->requestApi(
            'POST',
            '/open_api/v1.3/subscription/unsubscribe/',
            [
                'app_id' => $appId,
                'secret' => $secret,
                'subscription_id' => $subscriptionId,
            ]
        );
    }

    /**
     * Get subscriptions
     *
     * @param int $appId            # The APP ID
     * @param string $secret        # Secret
     * @param string $object        # The object that you want to subscribe to. Use LEAD for this endpoint
     * @param int|null $page        # The current page number. Default value: 1. Value range: ≥ 1
     * @param int|null $pageSize    # The page size. Default value:10. Value range: 1-1000
     *
     * @return array
     *
     * @throws Throwable
     */
    public function getSubscriptions(
        int $appId,
        string $secret,
        string $object = 'LEAD',
        ?int $page = null,
        ?int $pageSize = null
    ): array {
        return $this->requestApi(
            'GET',
            '/open_api/v1.3/subscription/get/',
            [
                'app_id' => $appId,
                'secret' => $secret,
                'object' => $object,
                'page' => $page,
                'page_size' => $pageSize
            ]
        );
    }
}


1			<?php
2
3			declare(strict_types=1);
4
5			namespace Promopult\TikTokMarketingApi\Service;
6
7			use Throwable;
8			use function json_decode;
9
10			/**
11			* @psalm-suppress UnusedClass
12			*/
13			final class Leads extends \Promopult\TikTokMarketingApi\AbstractService
14			{
15			/**
16			* Create test lead
17			*
18			* After the subscription, you can use the endpoints below to perform an end-to-end testing for leads generation,
19			* and clear the testing lead.
20			*
21			* @param ?int $advertiserId If the instant form and the generated leads are under an ad account, you must
22			* specify the advertiser ID.
23			* @param ?int $libraryId If the instant form and the generated leads are under a Business Center, you must
24			* specify the ID of the form library that contains the instant form and leads.
25			* @param int $pageId The ID of the instant form.
26			* @return array
27			*
28			* @throws Throwable
29			* @see https://ads.tiktok.com/marketing_api/docs?id=1701890943400962
30			*/
31			public function createTestLead(
32			?int $advertiserId,
33			?int $libraryId,
34			int $pageId
35			): array {
36			return $this->requestApi(
37			'POST',
38			'/open_api/v1.3/page/lead/mock/create/',
39			[
40			'advertiser_id' => $advertiserId,
41			'library_id' => $libraryId,
42			'page_id' => $pageId
43			]
44			);
45			}
46
47			/**
48			* Get test leads
49			*
50			* You can use this endpoint to get a test lead.
51			*
52			* @param ?int $advertiserId If the instant form and the generated leads are under an ad account, you must
53			* specify the advertiser ID.
54			* @param ?int $libraryId If the instant form and the generated leads are under a Business Center, you must
55			* specify the ID of the form library that contains the instant form and leads.
56			* @param int $pageId The ID of the instant form.
57			*
58			* @return array
59			*
60			* @throws Throwable
61			* @see https://ads.tiktok.com/marketing_api/docs?id=1709486980307969
62			*/
63			public function getTestLeads(
64			?int $advertiserId,
65			?int $libraryId,
66			int $pageId
67			): array {
68			return $this->requestApi(
69			'GET',
70			'/open_api/v1.3/page/lead/mock/get/',
71			[
72			'advertiser_id' => $advertiserId,
73			'library_id' => $libraryId,
74			'page_id' => $pageId
75			]
76			);
77			}
78
79			/**
80			* Delete a test lead
81			*
82			* You can use this endpoint to delete an existing test lead.
83			*
84			* @param int $advertiserId
85			* @param int $leadId
86			* @return array
87			*
88			* @throws Throwable
89			*
90			* @see https://ads.tiktok.com/marketing_api/docs?id=1709487026425858
91			*/
92			public function deleteTestLead(
93			int $advertiserId,
94			int $leadId
95			): array {
96			return $this->requestApi(
97			'POST',
98			'/open_api/v1.3/page/lead/mock/delete/',
99			[
100			'advertiser_id' => $advertiserId,
101			'lead_id' => $leadId
102			]
103			);
104			}
105
106			/**
107			* Create lead download task
108			*
109			* @param int $advertiserId
110			* @param int\|null $adId
111			* @param int\|null $pageId
112			* @return array
113			*
114			* @throws Throwable
115			*
116			* @see https://ads.tiktok.com/marketing_api/docs?id=1701890942344193
117			*/
118			public function createLeadDownloadTask(
119			int $advertiserId,
120			?int $adId = null,
121			?int $pageId = null
122			): array {
123			return $this->requestApi(
124			'GET',
125			'/open_api/v1.3/page/lead/task/',
126			[
127			'advertiser_id' => $advertiserId,
128			'ad_id' => $adId,
129			'page_id' => $pageId,
130			]
131			);
132			}
133
134			/**
135			* Get lead download task for status check
136			*
137			* Please note that the leads file will expire in 10 minutes after it was generated. You will get a file not exist
138			* error if the file has expired.
139			*
140			* @param int $advertiserId
141			* @param int $taskId
142			* @return array
143			*
144			* @throws Throwable
145			*
146			* @see https://ads.tiktok.com/marketing_api/docs?id=1701890942344193
147			*/
148			public function getLeadDownloadTask(
149			int $advertiserId,
150			int $taskId
151			): array {
152			return $this->requestApi(
153			'GET',
154			'/open_api/v1.3/page/lead/task/',
155			[
156			'advertiser_id' => $advertiserId,
157			'task_id' => $taskId
158			]
159			);
160			}
161
162			/**
163			* Download leads
164			*
165			* @param int $advertiserId
166			* @param int $taskId
167			*
168			* @return string
169			*
170			* @throws Throwable
171			*
172			* @see https://ads.tiktok.com/marketing_api/docs?id=1709486183758850
173			*/
174			public function downloadLeads(
175			int $advertiserId,
176			int $taskId
177			): string {
178			$url = $this->credentials->getApiBaseUrl()
179			. '/open_api/v1.3/page/lead/task/download/'
180			. '?' . $this->prepareGetParams([
181			'advertiser_id' => $advertiserId,
182			'task_id' => $taskId
183			]);
184
185			$headers = [
186			'Access-Token' => $this->credentials->getAccessToken(),
187			];
188
189			$request = new \GuzzleHttp\Psr7\Request(
190			'GET',
191			$url,
192			$headers,
193			null
194			);
195
196			$response = $this->sendRequest($request);
197
198			/** @var array $decodedJson */
199			$decodedJson = json_decode(
200			(string) $response->getBody(),
201			true
202			);
203
204			if (
205			isset($decodedJson['code'])
206			&& $decodedJson['code'] != 0
207			) {
208			throw new \Promopult\TikTokMarketingApi\Exception\ErrorResponse(
209			(int) $decodedJson['code'],
210			(string) $decodedJson['message'],
211			$request,
212			$response
213			);
214			}
215
216			return (string) $response->getBody();
217			}
218
219			/**
220			* Subscribe to leads
221			*
222			* You can subscribe to a page (instant form) to get leads generated from the page. If you do not want to receive
223			* leads from a page any more, you can cancel the subscription.
224			*
225			* You can also get all subscriptions for an advertiser.
226			*
227			* You can subscribe to leads that are generated from a lead ad (instant form). Subscriptions are organized based on
228			* Subcription IDs (subscription_id), not page IDs (page_id). Subscriptions are independent. A page can be included
229			* in multiple subscriptions. Subscription status changes of a page in one subscription do not affect the
230			* subscription status of this page in another subscription.
231			*
232			* @param int $appId
233			* @param string $secret
234			* @param array $subscriptionDetail
235			* @param string $url
236			* @param string $object
237			* @return array
238			*
239			* @throws Throwable
240			*
241			* @see https://ads.tiktok.com/marketing_api/docs?id=1701890942854146
242			*/
243			public function subscribeToLeads(
244			int $appId,
245			string $secret,
246			array $subscriptionDetail,
247			string $url,
248			string $object = 'LEAD'
249			): array {
250			return $this->requestApi(
251			'POST',
252			'/open_api/v1.3/subscription/subscribe/',
253			[
254			'app_id' => $appId,
255			'secret' => $secret,
256			'subscription_detail' => $subscriptionDetail,
257			'object' => $object,
258			'url' => $url
259			]
260			);
261			}
262
263			/**
264			* Cancel subscription
265			*
266			* @param int $appId
267			* @param string $secret
268			* @param int $subscriptionId
269			* @return array
270			*
271			* @throws Throwable
272			*
273			* @see https://ads.tiktok.com/marketing_api/docs?id=1709486460752897
274			*/
275			public function cancelSubscription(
276			int $appId,
277			string $secret,
278			int $subscriptionId
279			): array {
280			return $this->requestApi(
281			'POST',
282			'/open_api/v1.3/subscription/unsubscribe/',
283			[
284			'app_id' => $appId,
285			'secret' => $secret,
286			'subscription_id' => $subscriptionId,
287			]
288			);
289			}
290
291			/**
292			* Get subscriptions
293			*
294			* @param int $appId # The APP ID
295			* @param string $secret # Secret
296			* @param string $object # The object that you want to subscribe to. Use LEAD for this endpoint
297			* @param int\|null $page # The current page number. Default value: 1. Value range: ≥ 1
298			* @param int\|null $pageSize # The page size. Default value:10. Value range: 1-1000
299			*
300			* @return array
301			*
302			* @throws Throwable
303			*/
304			public function getSubscriptions(
305			int $appId,
306			string $secret,
307			string $object = 'LEAD',
308			?int $page = null,
309			?int $pageSize = null
310			): array {
311			return $this->requestApi(
312			'GET',
313			'/open_api/v1.3/subscription/get/',
314			[
315			'app_id' => $appId,
316			'secret' => $secret,
317			'object' => $object,
318			'page' => $page,
319			'page_size' => $pageSize
320			]
321			);
322			}
323			}
324

promopult / tiktok-marketing-api

Leads::subscribeToLeads() A last analyzed 2025-02-17 19:03 UTC

Complexity

Size

Duplication

Importance

Duplication Side-by-Side

Filter issues like

Leads::subscribeToLeads() A
last analyzed 2025-02-17 19:03 UTC