forked from gungoren/apple-search-ads-go
-
Notifications
You must be signed in to change notification settings - Fork 0
/
doc.go
124 lines (107 loc) · 4.58 KB
/
doc.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
/**
Copyright (C) 2021 Mehmet Gungoren.
This file is part of apple-search-ads-go, a package for working with Apple's
Search Ads API.
apple-search-ads-go is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
apple-search-ads-go is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with apple-search-ads-go. If not, see <http://www.gnu.org/licenses/>.
*/
/*
Package asa is a Go client library for accessing Apple's Apple Search Ads API.
Usage
Import the package as you normally would:
import "github.com/rhinonet/apple-search-ads-go/asa"
Construct a new Apple Search Ads client, then use the various services on the client to
access different parts of the Apple Search Ads API. For example:
client := asa.NewClient(nil)
params := &asa.SearchAppsQuery{
Query: "face",
ReturnOwnedApps: false,
}
// list all apps with the query "face"
apps, _, err := client.App.SearchApps(context.Background(), params)
The client is divided into logical chunks closely corresponding to the layout and structure
of Apple's own documentation at https://developer.apple.com/documentation/apple_search_ads.
For more sample code snippets, head over to the https://github.com/rhinonet/apple-search-ads-go/tree/master/examples directory.
Authentication
You may find that the code snippet above will always fail due to a lack of authorization.
The Apple Search Ads API has no methods that allow for unauthorized requests. To make it
easy to authenticate with Apple Search Ads, the apple-search-ads-go library offers a solution for signing
and rotating JSON Web Tokens automatically. For example, the above snippet could be made
to look a little more like this:
import (
"os"
"time"
"github.com/rhinonet/apple-search-ads-go/asa"
)
func main() {
// Organization ID in Apple Search Ads
orgID := "...."
// Key ID for the given private key, described in Apple Search Ads
keyID := "...."
// Team ID for the given private key for the Apple Search Ads
teamID := "...."
// ClientID ID for the given private key for the Apple Search Ads
clientID := "...."
// A duration value for the lifetime of a token. Apple Search Ads does not accept a token with a lifetime of longer than 20 minutes
expiryDuration = 20*time.Minute
// The bytes of the private key created you have uploaded to it Apple Search Ads.
privateKey = os.ReadFile("path/to/key")
auth, err := asa.NewTokenConfig(orgID, keyID, teamID, clientID, expiryDuration, privateKey)
if err != nil {
return nil, err
}
client := asa.NewClient(auth.Client())
// list all apps with the "face" in the authenticated user's team
params := &asa.SearchAppsQuery{
Offset: 0,
Limit: 100,
Query: "face",
ReturnOwnedApps: true,
}
apps, _, err := client.App.SearchApps(context.Background(), params)
if err != nil {
return nil, err
}
}
The authenticated client created here will automatically regenerate the token if it expires.
Also note that all Apple Search Ads APIs are scoped to the credentials of the pre-configured key,
so you can't use this API to make queries against the entire App Store. For more information on
creating the necessary credentials for the Apple Search Ads API, see the documentation at
https://developer.apple.com/documentation/appstoreconnectapi/creating_api_keys_for_app_store_connect_api.
Pagination
All requests for resource collections (apps, acls, ad groups, campaigns, etc.) support pagination.
Responses for paginated resources will contain a Pagination property of type PageDetail,
with TotalResults, StartIndex and ItemsPerPage.
auth, _ := asa.NewTokenConfig(orgID, keyID, teamID, clientID, expiryDuration, privateKey)
client := asa.NewClient(auth.Client())
var allApps []asa.AppInfo
params := &asa.SearchAppsQuery{
Offset: 0,
Limit: 100,
Query: "face",
ReturnOwnedApps: false,
}
for {
apps, _, err := client.App.SearchApps(context.Background(), params)
if err != nil {
return nil, err
}
allApps = append(allApps, apps.AppInfos...)
pageDetail := apps.Pagination
lastOffset := pageDetail.StartIndex + len(apps.AppInfos)
if lastOffset < pageDetail.TotalResults {
params.Offset += int32(len(apps.AppInfos))
} else {
break
}
}
*/
package asa